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,
66 : const uint128_t& masterNodeID,
67 : const uint32_t height = 0 );
68 :
69 : /**
70 : * Construct and join a distributed barrier.
71 : *
72 : * @param localNode the local node to map the barrier to
73 : * @param barrier the identifier and version of the barrier
74 : * @sa isGood()
75 : * @version 1.1.1
76 : */
77 : CO_API Barrier( LocalNodePtr localNode, const ObjectVersion& barrier );
78 :
79 : /** Destruct the barrier. @version 1.0 */
80 : CO_API virtual ~Barrier();
81 :
82 : /**
83 : * @name Data Access
84 : *
85 : * After a change, the barrier has to be committed and synced to the same
86 : * version on all nodes entering the barrier.
87 : */
88 : //@{
89 : /** @return true if the barrier was created successfully. @version 1.1.1 */
90 428 : bool isGood() const { return isAttached(); }
91 :
92 : /** Set the number of participants in the barrier. @version 1.0 */
93 : CO_API void setHeight( const uint32_t height );
94 :
95 : /** Add one participant to the barrier. @version 1.0 */
96 : CO_API void increase();
97 :
98 : /** @return the number of participants. @version 1.0 */
99 : CO_API uint32_t getHeight() const;
100 : //@}
101 :
102 : /** @name Operations */
103 : //@{
104 : /**
105 : * Enter the barrier, blocks until the barrier has been reached.
106 : *
107 : * The implementation currently assumes that the master node instance
108 : * also enters the barrier.
109 : *
110 : * @return true on success, false on timeout or error.
111 : * @version 1.0
112 : */
113 : CO_API bool enter( const uint32_t timeout = LB_TIMEOUT_INDEFINITE );
114 : //@}
115 :
116 : protected:
117 : /** @internal */
118 : //@{
119 : void attach( const uint128_t& id, const uint32_t instanceID ) override;
120 31 : ChangeType getChangeType() const override { return DELTA; }
121 :
122 : void getInstanceData( DataOStream& os ) override;
123 : void applyInstanceData( DataIStream& is ) override;
124 : void pack( DataOStream& os ) override;
125 : void unpack( DataIStream& is ) override;
126 : //@}
127 :
128 : private:
129 : detail::Barrier* const _impl;
130 :
131 : void _cleanup( const uint64_t time );
132 : void _sendNotify( const uint128_t& version, NodePtr node );
133 :
134 : /* The command handlers. */
135 : bool _cmdEnter( ICommand& command );
136 : bool _cmdEnterReply( ICommand& command );
137 :
138 62 : LB_TS_VAR( _thread );
139 : };
140 : }
141 :
142 : #endif // CO_BARRIER_H
|