Line data Source code
1 :
2 : /* Copyright (c) 2005-2017, 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/connection.h> // used in inline template method
26 : #include <co/dispatcher.h> // base class
27 : #include <co/nodeType.h> // for NODETYPE_NODE enum
28 : #include <co/types.h>
29 :
30 : namespace co
31 : {
32 : namespace detail
33 : {
34 : class Node;
35 : }
36 :
37 : /**
38 : * Proxy node representing a remote LocalNode.
39 : *
40 : * A node represents a separate entity in a peer-to-peer network, typically a
41 : * process on another machine. It should have at least one Connection through
42 : * which is reachable. A Node provides the basic communication facilities
43 : * through message passing.
44 : */
45 : class Node : public Dispatcher, public lunchbox::Referenced
46 : {
47 : public:
48 : /**
49 : * Construct a new node proxy.
50 : *
51 : * @param type the type of the node, used during connect().
52 : * @version 1.0
53 : */
54 : CO_API explicit Node(const uint32_t type = co::NODETYPE_NODE);
55 :
56 : /** @name Data Access */
57 : //@{
58 : /**
59 : * Get the node's unique identifier.
60 : *
61 : * In rare cases (two nodes initiate a two-sided LocalNode::connect()) to
62 : * each other, two node instances with the same identifier might exist
63 : * temporarily during the connection handshake.
64 : *
65 : * @return the node's unique identifier.
66 : * @version 1.0
67 : */
68 : CO_API const NodeID& getNodeID() const;
69 :
70 : /** @return the type of the node. @version 1.0 */
71 : CO_API uint32_t getType() const;
72 :
73 : bool operator==(const Node* n) const; //!< @internal
74 :
75 : /** @return true if the node can send/receive messages. @version 1.0 */
76 : CO_API bool isReachable() const;
77 :
78 : /** @return true if the remote node is reachable. @version 1.0 */
79 : CO_API bool isConnected() const;
80 :
81 : /** @return true if the local node is reachable. @version 1.0 */
82 : CO_API bool isListening() const;
83 :
84 : /** @return true if then node is not active. @version 1.0 */
85 : CO_API bool isClosed() const;
86 :
87 : /** @return true if the node is about to become inactive. @version 1.0*/
88 : CO_API bool isClosing() const;
89 : //@}
90 :
91 : /** @name Connectivity information */
92 : //@{
93 : /** @return true if the node is local (listening). @version 1.0 */
94 135 : bool isLocal() const { return isListening(); }
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 otherwise.
112 : * @version 1.0
113 : */
114 : CO_API bool removeConnectionDescription(ConnectionDescriptionPtr cd);
115 :
116 : /** @return the connection descriptions. @version 1.0 */
117 : CO_API ConnectionDescriptions getConnectionDescriptions() const;
118 :
119 : /**
120 : * Get an active connection to this node.
121 : *
122 : * @param multicast if true, prefer a multicast connection.
123 : * @return an active connection to this node.
124 : * @version 1.0
125 : */
126 : CO_API ConnectionPtr getConnection(const bool multicast = false);
127 : //@}
128 :
129 : /** @name Messaging API */
130 : //@{
131 : /**
132 : * Send a command with optional data to the node.
133 : *
134 : * The returned command can be used to pass additional data. The data will
135 : * be send after the command object is destroyed, aka when it is running out
136 : * of scope. Thread safe.
137 : *
138 : * @param cmd the node command to execute.
139 : * @param multicast prefer multicast connection for sending.
140 : * @return the command object to append additional data.
141 : * @version 1.0
142 : */
143 : CO_API OCommand send(const uint32_t cmd, const bool multicast = false);
144 :
145 : /**
146 : * Send a custom command with optional data to the node.
147 : *
148 : * The command handler for this command being send is registered with the
149 : * remote LocalNode::registerCommandHandler().
150 : *
151 : * The returned command can be used to pass additional data. The data will
152 : * be send after the command object is destroyed, aka when it is running out
153 : * of scope. Thread safe.
154 : *
155 : * @param commandID the ID of the registered custom command.
156 : * @param multicast prefer multicast connection for sending.
157 : * @return the command object to append additional data.
158 : * @version 1.0
159 : */
160 : CO_API CustomOCommand send(const uint128_t& commandID,
161 : const bool multicast = false);
162 : //@}
163 :
164 : /** @name Launch parameters */
165 : //@{
166 : /** Set the host name for the launch command. */
167 : CO_API void setHostname(const std::string& host);
168 :
169 : /** @return the host name for the launch command. */
170 : CO_API const std::string& getHostname() const;
171 :
172 : /** @return the working directory for the remote process. */
173 : CO_API virtual std::string getWorkDir() const;
174 :
175 : /** @return the character to quote single arguments. */
176 : CO_API virtual std::string getLaunchQuote() const;
177 : //@}
178 :
179 : /** @internal @return last receive time. */
180 : CO_API int64_t getLastReceiveTime() const;
181 :
182 : /** @internal Serialize the node's information. */
183 : CO_API std::string serialize() const;
184 : /** @internal Deserialize the node information, consumes given data. */
185 : CO_API bool deserialize(std::string& data);
186 :
187 : protected:
188 : /** Destruct this node. @version 1.0 */
189 : CO_API virtual ~Node();
190 :
191 : /** @internal */
192 : void _addConnectionDescription(ConnectionDescriptionPtr cd);
193 : /** @internal */
194 : bool _removeConnectionDescription(ConnectionDescriptionPtr cd);
195 :
196 : /** @internal @return the active multicast connection to this node. */
197 : ConnectionPtr _getMulticast() const;
198 :
199 : /**
200 : * Activate and return a multicast connection.
201 : *
202 : * Multicast connections are activated lazily on first use, since they
203 : * trigger the creation of the remote local node proxies on all members of
204 : * the multicast group.
205 : *
206 : * @return the first usable multicast connection to this node, or 0.
207 : * @version 1.0
208 : */
209 : ConnectionPtr getMulticast();
210 :
211 : private:
212 : detail::Node* const _impl;
213 : CO_API friend std::ostream& operator<<(std::ostream&, const Node&);
214 :
215 : /** Ensures the connectivity of this node. */
216 : ConnectionPtr _getConnection(const bool preferMulticast);
217 :
218 : /** @internal @name Methods for LocalNode */
219 : //@{
220 : void _addMulticast(NodePtr node, ConnectionPtr connection);
221 : void _removeMulticast(ConnectionPtr connection);
222 : void _connectMulticast(NodePtr node);
223 : void _connectMulticast(NodePtr node, ConnectionPtr connection);
224 : void _setListening();
225 : void _setClosing();
226 : void _setClosed();
227 : void _connect(ConnectionPtr connection);
228 : void _disconnect();
229 : void _setLastReceive(const int64_t time);
230 : friend class LocalNode;
231 : //@}
232 : };
233 :
234 : CO_API std::ostream& operator<<(std::ostream& os, const Node& node);
235 : }
236 :
237 : #endif // CO_NODE_H
|
