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
30 : {
31 : class Barrier;
32 : }
33 :
34 : /**
35 : * A networked, versioned barrier.
36 : *
37 : * On a given LocalNode only one instance of a given barrier can be mapped,
38 : * i.e., multiple instances of the same barrier are currently not supported by
39 : * the implementation. Not intended to be subclassed.
40 : */
41 : class Barrier : public Object
42 : {
43 : public:
44 : /**
45 : * Construct and register a new distributed barrier.
46 : *
47 : * Barriers are versioned, distributed objects. This constructor creates and
48 : * registers the barrier with its LocalNode. Other processes contributing to
49 : * the barrier use the other constructor to create and map an instance to
50 : * this master version.
51 : *
52 : * The master node will maintain the barrier state. It has to be reachable
53 : * from all other nodes participating in the barrier. If the master node
54 : * identifier is not an UUID, the local node is used as the master.
55 : *
56 : * Note that the node of the object master, i.e., the instance which is
57 : * registered through this constructor, and the barrier's master node may be
58 : * different. The barriers master node maintains the barrier state. The user
59 : * of the barrier has to ensure that the given master node has at least one
60 : * instance of the barrier.
61 : *
62 : * @param localNode the local node to register the barrier with.
63 : * @param masterNodeID the master node identifier.
64 : * @param height the initial group size for the barrier.
65 : * @sa isGood()
66 : * @version 1.1.1
67 : */
68 : CO_API Barrier(LocalNodePtr localNode, const uint128_t& masterNodeID,
69 : const uint32_t height = 0);
70 :
71 : /**
72 : * Construct and join a distributed barrier.
73 : *
74 : * @param localNode the local node to map the barrier to
75 : * @param barrier the identifier and version of the barrier
76 : * @sa isGood()
77 : * @version 1.1.1
78 : */
79 : CO_API Barrier(LocalNodePtr localNode, const ObjectVersion& barrier);
80 :
81 : /** Destruct the barrier. @version 1.0 */
82 : CO_API virtual ~Barrier();
83 :
84 : /**
85 : * @name Data Access
86 : *
87 : * After a change, the barrier has to be committed and synced to the same
88 : * version on all nodes entering the barrier.
89 : */
90 : //@{
91 : /** @return true if the barrier was created successfully. @version 1.1.1 */
92 424 : bool isGood() const { return isAttached(); }
93 : /** Set the number of participants in the barrier. @version 1.0 */
94 : CO_API void setHeight(const uint32_t height);
95 :
96 : /** Add one participant to the barrier. @version 1.0 */
97 : CO_API void increase();
98 :
99 : /** @return the number of participants. @version 1.0 */
100 : CO_API uint32_t getHeight() const;
101 : //@}
102 :
103 : /** @name Operations */
104 : //@{
105 : /**
106 : * Enter the barrier, blocks until the barrier has been reached.
107 : *
108 : * The implementation currently assumes that the master node instance
109 : * also enters the barrier.
110 : *
111 : * @return true on success, false on timeout or error.
112 : * @version 1.0
113 : */
114 : CO_API bool enter(const uint32_t timeout = LB_TIMEOUT_INDEFINITE);
115 : //@}
116 :
117 : protected:
118 : /** @internal */
119 : //@{
120 : void attach(const uint128_t& id, const uint32_t instanceID) override;
121 31 : ChangeType getChangeType() const override { return DELTA; }
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
|
