Line data Source code
1 :
2 : /* Copyright (c) 2005-2013, Stefan Eilemann <eile@equalizergraphics.com>
3 : * 2010, Cedric Stalder <cedric.stalder@gmail.com>
4 : * 2012-2014, Daniel Nachbaur <danielnachbaur@gmail.com>
5 : *
6 : * This file is part of Collage <https://github.com/Eyescale/Collage>
7 : *
8 : * This library is free software; you can redistribute it and/or modify it under
9 : * the terms of the GNU Lesser General Public License version 2.1 as published
10 : * by the Free Software Foundation.
11 : *
12 : * This library is distributed in the hope that it will be useful, but WITHOUT
13 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
15 : * details.
16 : *
17 : * You should have received a copy of the GNU Lesser General Public License
18 : * along with this library; if not, write to the Free Software Foundation, Inc.,
19 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20 : */
21 :
22 : #ifndef CO_NODE_H
23 : #define CO_NODE_H
24 :
25 : #include <co/dispatcher.h> // base class
26 : #include <co/connection.h> // used in inline template method
27 : #include <co/nodeType.h> // for NODETYPE_NODE enum
28 : #include <co/types.h>
29 :
30 : namespace co
31 : {
32 : namespace detail { class Node; }
33 :
34 : /**
35 : * Proxy node representing a remote LocalNode.
36 : *
37 : * A node represents a separate entity in a peer-to-peer network, typically
38 : * a process on another machine. It should have at least one Connection
39 : * through which is reachable. A Node provides the basic communication
40 : * facilities through message passing.
41 : */
42 : class Node : public Dispatcher, public lunchbox::Referenced
43 : {
44 : public:
45 : /**
46 : * Construct a new node proxy.
47 : *
48 : * @param type the type of the node, used during connect().
49 : * @version 1.0
50 : */
51 : CO_API explicit Node( const uint32_t type = co::NODETYPE_NODE );
52 :
53 : /** @name Data Access */
54 : //@{
55 : /**
56 : * Get the node's unique identifier.
57 : *
58 : * In rare cases (two nodes initiate a two-sided LocalNode::connect())
59 : * to each other, two node instances with the same identifier might
60 : * exist temporarily during the connection handshake.
61 : *
62 : * @return the node's unique identifier.
63 : * @version 1.0
64 : */
65 : CO_API const NodeID& getNodeID() const;
66 :
67 :
68 : /** @return the type of the node. @version 1.0 */
69 : CO_API uint32_t getType() const;
70 :
71 : bool operator == ( const Node* n ) const; //!< @internal
72 : bool isBigEndian() const; //!< @internal
73 :
74 : /** @return true if the node can send/receive messages. @version 1.0 */
75 : CO_API bool isReachable() const;
76 :
77 : /** @return true if the remote node is reachable. @version 1.0 */
78 : CO_API bool isConnected() const;
79 :
80 : /** @return true if the local node is reachable. @version 1.0 */
81 : CO_API bool isListening() const;
82 :
83 : /** @return true if then node is not active. @version 1.0 */
84 : CO_API bool isClosed() const;
85 :
86 : /** @return true if the node is about to become inactive. @version 1.0*/
87 : CO_API bool isClosing() const;
88 : //@}
89 :
90 : /** @name Connectivity information */
91 : //@{
92 : /** @return true if the node is local (listening). @version 1.0 */
93 135 : bool isLocal() const { return isListening(); }
94 :
95 : /**
96 : * Add a new description how this node can be reached.
97 : *
98 : * The node has to be closed.
99 : *
100 : * @param cd the connection description.
101 : * @version 1.0
102 : */
103 : CO_API void addConnectionDescription( ConnectionDescriptionPtr cd );
104 :
105 : /**
106 : * Removes a connection description.
107 : *
108 : * The node has to be closed.
109 : *
110 : * @param cd the connection description.
111 : * @return true if the connection description was removed, false
112 : * otherwise.
113 : * @version 1.0
114 : */
115 : CO_API bool removeConnectionDescription( ConnectionDescriptionPtr cd );
116 :
117 : /** @return the connection descriptions. @version 1.0 */
118 : CO_API ConnectionDescriptions getConnectionDescriptions() const;
119 :
120 : /**
121 : * Get an active connection to this node.
122 : *
123 : * @param multicast if true, prefer a multicast connection.
124 : * @return an active connection to this node.
125 : * @version 1.0
126 : */
127 : CO_API ConnectionPtr getConnection( const bool multicast = false );
128 : //@}
129 :
130 : /** @name Messaging API */
131 : //@{
132 : /**
133 : * Send a command with optional data to the node.
134 : *
135 : * The returned command can be used to pass additional data. The data
136 : * will be send after the command object is destroyed, aka when it is
137 : * running out of scope. Thread safe.
138 : *
139 : * @param cmd the node command to execute.
140 : * @param multicast prefer multicast connection for sending.
141 : * @return the command object to append additional data.
142 : * @version 1.0
143 : */
144 : CO_API OCommand send( const uint32_t cmd, const bool multicast = false);
145 :
146 : /**
147 : * Send a custom command with optional data to the node.
148 : *
149 : * The command handler for this command being send is registered with
150 : * the remote LocalNode::registerCommandHandler().
151 : *
152 : * The returned command can be used to pass additional data. The data
153 : * will be send after the command object is destroyed, aka when it is
154 : * running out of scope. Thread safe.
155 : *
156 : * @param commandID the ID of the registered custom command.
157 : * @param multicast prefer multicast connection for sending.
158 : * @return the command object to append additional data.
159 : * @version 1.0
160 : */
161 : CO_API CustomOCommand send( const uint128_t& commandID,
162 : const bool multicast = false );
163 : //@}
164 :
165 : /** @internal @return last receive time. */
166 : CO_API int64_t getLastReceiveTime() const;
167 :
168 : /** @internal Serialize the node's information. */
169 : CO_API std::string serialize() const;
170 : /** @internal Deserialize the node information, consumes given data. */
171 : CO_API bool deserialize( std::string& data );
172 :
173 : protected:
174 : /** Destruct this node. @version 1.0 */
175 : CO_API virtual ~Node();
176 :
177 : /** @internal */
178 : void _addConnectionDescription( ConnectionDescriptionPtr cd );
179 : /** @internal */
180 : bool _removeConnectionDescription( ConnectionDescriptionPtr cd );
181 :
182 : /** @internal @return the active multicast connection to this node. */
183 : ConnectionPtr _getMulticast() const;
184 :
185 : /**
186 : * Activate and return a multicast connection.
187 : *
188 : * Multicast connections are activated lazily on first use, since they
189 : * trigger the creation of the remote local node proxies on all members
190 : * of the multicast group.
191 : *
192 : * @return the first usable multicast connection to this node, or 0.
193 : * @version 1.0
194 : */
195 : ConnectionPtr getMulticast();
196 :
197 : private:
198 : detail::Node* const _impl;
199 : CO_API friend std::ostream& operator << ( std::ostream&, const Node& );
200 :
201 : /** Ensures the connectivity of this node. */
202 : ConnectionPtr _getConnection( const bool preferMulticast );
203 :
204 : /** @internal @name Methods for LocalNode */
205 : //@{
206 : void _addMulticast( NodePtr node, ConnectionPtr connection );
207 : void _removeMulticast( ConnectionPtr connection );
208 : void _connectMulticast( NodePtr node );
209 : void _connectMulticast( NodePtr node, ConnectionPtr connection );
210 : void _setListening();
211 : void _setClosing();
212 : void _setClosed();
213 : void _connect( ConnectionPtr connection );
214 : void _disconnect();
215 : void _setLastReceive( const int64_t time );
216 : friend class LocalNode;
217 : //@}
218 : };
219 :
220 : CO_API std::ostream& operator << ( std::ostream& os, const Node& node );
221 : }
222 :
223 : namespace lunchbox
224 : {
225 0 : template<> inline void byteswap( co::Node*& ) { /*NOP*/ }
226 : template<> inline void byteswap( co::NodePtr& ) { /*NOP*/ }
227 : }
228 :
229 : #endif // CO_NODE_H
|
