Line data Source code
1 :
2 : /* Copyright (c) 2006-2014, Stefan Eilemann <eile@equalizergraphics.com>
3 : * 2011, Cedric Stalder <cedric.stalder@gmail.com>
4 : *
5 : * This file is part of Collage <https://github.com/Eyescale/Collage>
6 : *
7 : * This library is free software; you can redistribute it and/or modify it under
8 : * the terms of the GNU Lesser General Public License version 2.1 as published
9 : * by the Free Software Foundation.
10 : *
11 : * This library is distributed in the hope that it will be useful, but WITHOUT
12 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
14 : * details.
15 : *
16 : * You should have received a copy of the GNU Lesser General Public License
17 : * along with this library; if not, write to the Free Software Foundation, Inc.,
18 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 : */
20 :
21 : #ifndef CO_BARRIER_H
22 : #define CO_BARRIER_H
23 :
24 : #include <co/object.h> // base class
25 : #include <co/types.h>
26 :
27 : namespace co
28 : {
29 : namespace detail { class Barrier; }
30 :
31 : /**
32 : * A networked, versioned barrier.
33 : *
34 : * On a given LocalNode only one instance of a given barrier can be mapped,
35 : * i.e., multiple instances of the same barrier are currently not supported by
36 : * the implementation. Not intended to be subclassed.
37 : */
38 : class Barrier : public Object
39 : {
40 : public:
41 : /**
42 : * Construct and register a new distributed barrier.
43 : *
44 : * Barriers are versioned, distributed objects. This constructor creates and
45 : * registers the barrier with its LocalNode. Other processes contributing to
46 : * the barrier use the other constructor to create and map an instance to
47 : * this master version.
48 : *
49 : * The master node will maintain the barrier state. It has to be reachable
50 : * from all other nodes participating in the barrier. If the master node
51 : * identifier is not an UUID, the local node is used as the master.
52 : *
53 : * Note that the node of the object master, i.e., the instance which is
54 : * registered through this constructor, and the barrier's master node may be
55 : * different. The barriers master node maintains the barrier state. The user
56 : * of the barrier has to ensure that the given master node has at least one
57 : * instance of the barrier.
58 : *
59 : * @param localNode the local node to register the barrier with.
60 : * @param masterNodeID the master node identifier.
61 : * @param height the initial group size for the barrier.
62 : * @sa isGood()
63 : * @version 1.1.1
64 : */
65 : CO_API Barrier( LocalNodePtr localNode, const uint128_t& masterNodeID,
66 : const uint32_t height = 0 );
67 :
68 : /**
69 : * Construct and join a distributed barrier.
70 : *
71 : * @param localNode the local node to map the barrier to
72 : * @param barrier the identifier and version of the barrier
73 : * @sa isGood()
74 : * @version 1.1.1
75 : */
76 : CO_API Barrier( LocalNodePtr localNode, const ObjectVersion& barrier );
77 :
78 : /** Destruct the barrier. @version 1.0 */
79 : CO_API virtual ~Barrier();
80 :
81 : /**
82 : * @name Data Access
83 : *
84 : * After a change, the barrier has to be committed and synced to the same
85 : * version on all nodes entering the barrier.
86 : */
87 : //@{
88 : /** @return true if the barrier was created successfully. @version 1.1.1 */
89 425 : bool isGood() const { return isAttached(); }
90 :
91 : /** Set the number of participants in the barrier. @version 1.0 */
92 : CO_API void setHeight( const uint32_t height );
93 :
94 : /** Add one participant to the barrier. @version 1.0 */
95 : CO_API void increase();
96 :
97 : /** @return the number of participants. @version 1.0 */
98 : CO_API uint32_t getHeight() const;
99 : //@}
100 :
101 : /** @name Operations */
102 : //@{
103 : /**
104 : * Enter the barrier, blocks until the barrier has been reached.
105 : *
106 : * The implementation currently assumes that the master node instance
107 : * also enters the barrier.
108 : *
109 : * @return true on success, false on timeout or error.
110 : * @version 1.0
111 : */
112 : CO_API bool enter( const uint32_t timeout = LB_TIMEOUT_INDEFINITE );
113 : //@}
114 :
115 : protected:
116 : /** @internal */
117 : //@{
118 : void attach( const uint128_t& id, const uint32_t instanceID ) override;
119 31 : ChangeType getChangeType() const override { return DELTA; }
120 :
121 : void getInstanceData( DataOStream& os ) override;
122 : void applyInstanceData( DataIStream& is ) override;
123 : void pack( DataOStream& os ) override;
124 : void unpack( DataIStream& is ) override;
125 : //@}
126 :
127 : private:
128 : detail::Barrier* const _impl;
129 :
130 : void _cleanup( const uint64_t time );
131 : void _sendNotify( const uint128_t& version, NodePtr node );
132 :
133 : /* The command handlers. */
134 : bool _cmdEnter( ICommand& command );
135 : bool _cmdEnterReply( ICommand& command );
136 :
137 62 : LB_TS_VAR( _thread );
138 : };
139 : }
140 :
141 : #endif // CO_BARRIER_H
|
