Line data Source code
1 :
2 : /* Copyright (c) 2005-2016, Stefan Eilemann <eile@equalizergraphics.com>
3 : * Cedric Stalder <cedric.stalder@gmail.com>
4 : * 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 a
38 : * process on another machine. It should have at least one Connection through
39 : * which is reachable. A Node provides the basic communication facilities
40 : * 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()) to
59 : * each other, two node instances with the same identifier might exist
60 : * 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 : /** @return the type of the node. @version 1.0 */
68 : CO_API uint32_t getType() const;
69 :
70 : bool operator == ( const Node* n ) const; //!< @internal
71 : bool isBigEndian() const; //!< @internal
72 :
73 : /** @return true if the node can send/receive messages. @version 1.0 */
74 : CO_API bool isReachable() const;
75 :
76 : /** @return true if the remote node is reachable. @version 1.0 */
77 : CO_API bool isConnected() const;
78 :
79 : /** @return true if the local node is reachable. @version 1.0 */
80 : CO_API bool isListening() const;
81 :
82 : /** @return true if then node is not active. @version 1.0 */
83 : CO_API bool isClosed() const;
84 :
85 : /** @return true if the node is about to become inactive. @version 1.0*/
86 : CO_API bool isClosing() const;
87 : //@}
88 :
89 : /** @name Connectivity information */
90 : //@{
91 : /** @return true if the node is local (listening). @version 1.0 */
92 135 : bool isLocal() const { return isListening(); }
93 :
94 : /**
95 : * Add a new description how this node can be reached.
96 : *
97 : * The node has to be closed.
98 : *
99 : * @param cd the connection description.
100 : * @version 1.0
101 : */
102 : CO_API void addConnectionDescription( ConnectionDescriptionPtr cd );
103 :
104 : /**
105 : * Removes a connection description.
106 : *
107 : * The node has to be closed.
108 : *
109 : * @param cd the connection description.
110 : * @return true if the connection description was removed, false otherwise.
111 : * @version 1.0
112 : */
113 : CO_API bool removeConnectionDescription( ConnectionDescriptionPtr cd );
114 :
115 : /** @return the connection descriptions. @version 1.0 */
116 : CO_API ConnectionDescriptions getConnectionDescriptions() const;
117 :
118 : /**
119 : * Get an active connection to this node.
120 : *
121 : * @param multicast if true, prefer a multicast connection.
122 : * @return an active connection to this node.
123 : * @version 1.0
124 : */
125 : CO_API ConnectionPtr getConnection( const bool multicast = false );
126 : //@}
127 :
128 : /** @name Messaging API */
129 : //@{
130 : /**
131 : * Send a command with optional data to the node.
132 : *
133 : * The returned command can be used to pass additional data. The data will
134 : * be send after the command object is destroyed, aka when it is running out
135 : * of scope. Thread safe.
136 : *
137 : * @param cmd the node command to execute.
138 : * @param multicast prefer multicast connection for sending.
139 : * @return the command object to append additional data.
140 : * @version 1.0
141 : */
142 : CO_API OCommand send( const uint32_t cmd, const bool multicast = false);
143 :
144 : /**
145 : * Send a custom command with optional data to the node.
146 : *
147 : * The command handler for this command being send is registered with the
148 : * remote LocalNode::registerCommandHandler().
149 : *
150 : * The returned command can be used to pass additional data. The data will
151 : * be send after the command object is destroyed, aka when it is running out
152 : * of scope. Thread safe.
153 : *
154 : * @param commandID the ID of the registered custom command.
155 : * @param multicast prefer multicast connection for sending.
156 : * @return the command object to append additional data.
157 : * @version 1.0
158 : */
159 : CO_API CustomOCommand send( const uint128_t& commandID,
160 : const bool multicast = false );
161 : //@}
162 :
163 : /** @name Launch parameters */
164 : //@{
165 : /** Set the host name for the launch command. */
166 : CO_API void setHostname( const std::string& host );
167 :
168 : /** @return the host name for the launch command. */
169 : CO_API const std::string& getHostname() const;
170 :
171 : /** @return the working directory for the remote process. */
172 : CO_API virtual std::string getWorkDir() const;
173 :
174 : /** @return the character to quote single arguments. */
175 : CO_API virtual std::string getLaunchQuote() const;
176 : //@}
177 :
178 : /** @internal @return last receive time. */
179 : CO_API int64_t getLastReceiveTime() const;
180 :
181 : /** @internal Serialize the node's information. */
182 : CO_API std::string serialize() const;
183 : /** @internal Deserialize the node information, consumes given data. */
184 : CO_API bool deserialize( std::string& data );
185 :
186 : protected:
187 : /** Destruct this node. @version 1.0 */
188 : CO_API virtual ~Node();
189 :
190 : /** @internal */
191 : void _addConnectionDescription( ConnectionDescriptionPtr cd );
192 : /** @internal */
193 : bool _removeConnectionDescription( ConnectionDescriptionPtr cd );
194 :
195 : /** @internal @return the active multicast connection to this node. */
196 : ConnectionPtr _getMulticast() const;
197 :
198 : /**
199 : * Activate and return a multicast connection.
200 : *
201 : * Multicast connections are activated lazily on first use, since they
202 : * trigger the creation of the remote local node proxies on all members of
203 : * the multicast group.
204 : *
205 : * @return the first usable multicast connection to this node, or 0.
206 : * @version 1.0
207 : */
208 : ConnectionPtr getMulticast();
209 :
210 : private:
211 : detail::Node* const _impl;
212 : CO_API friend std::ostream& operator << ( std::ostream&, const Node& );
213 :
214 : /** Ensures the connectivity of this node. */
215 : ConnectionPtr _getConnection( const bool preferMulticast );
216 :
217 : /** @internal @name Methods for LocalNode */
218 : //@{
219 : void _addMulticast( NodePtr node, ConnectionPtr connection );
220 : void _removeMulticast( ConnectionPtr connection );
221 : void _connectMulticast( NodePtr node );
222 : void _connectMulticast( NodePtr node, ConnectionPtr connection );
223 : void _setListening();
224 : void _setClosing();
225 : void _setClosed();
226 : void _connect( ConnectionPtr connection );
227 : void _disconnect();
228 : void _setLastReceive( const int64_t time );
229 : friend class LocalNode;
230 : //@}
231 : };
232 :
233 : CO_API std::ostream& operator << ( std::ostream& os, const Node& node );
234 : }
235 :
236 : namespace lunchbox
237 : {
238 0 : template<> inline void byteswap( co::Node*& ) { /*NOP*/ }
239 : template<> inline void byteswap( co::NodePtr& ) { /*NOP*/ }
240 : }
241 :
242 : #endif // CO_NODE_H
|
