source: source/ariba/Node.h@ 3067

Last change on this file since 3067 was 3067, checked in by Christoph Mayer, 16 years ago

-fixed #30 (stress test pingpong, has some errors), #24 (autolinks for easy message sending)
File size: 10.6 KB
Line 
1// [License]
2// The Ariba-Underlay Copyright
3//
4// Copyright (c) 2008-2009, Institute of Telematics, UniversitÀt Karlsruhe (TH)
5//
6// Institute of Telematics
7// UniversitÀt Karlsruhe (TH)
8// Zirkel 2, 76128 Karlsruhe
9// Germany
10//
11// Redistribution and use in source and binary forms, with or without
12// modification, are permitted provided that the following conditions are
13// met:
14//
15// 1. Redistributions of source code must retain the above copyright
16// notice, this list of conditions and the following disclaimer.
17// 2. Redistributions in binary form must reproduce the above copyright
18// notice, this list of conditions and the following disclaimer in the
19// documentation and/or other materials provided with the distribution.
20//
21// THIS SOFTWARE IS PROVIDED BY THE INSTITUTE OF TELEMATICS ``AS IS'' AND
22// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OF TELEMATICS OR
25// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
26// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
27// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
29// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32//
33// The views and conclusions contained in the software and documentation
34// are those of the authors and should not be interpreted as representing
35// official policies, either expressed or implied, of the Institute of
36// Telematics.
37// [License]
38
39#ifndef NODE_H_
40#define NODE_H_
41
42// forward declarations
43namespace ariba {
44 class Node;
45 namespace overlay {
46 class BaseOverlay;
47 }
48}
49
50#include <vector>
51#include "Module.h"
52#include "Identifiers.h"
53#include "SpoVNetProperties.h"
54#include "NodeListener.h"
55#include "Name.h"
56#include "AribaModule.h"
57#include "CommunicationListener.h"
58#include "DataMessage.h"
59
60using ariba::overlay::BaseOverlay;
61using std::vector;
62
63namespace ariba {
64
65/**
66 * This class should implement all ariba node functionality.
67 *
68 * @author Sebastian Mies <mies@tm.uka.de>
69 * @author Christoph Mayer <mayer@tm.uka.de>
70 */
71class Node: public Module {
72public:
73 /**
74 * Constructs a new node using a given ariba module
75 *
76 * @param ariba_mod The ariba module
77 * @param name The canonical node name of the new node. When NULL a
78 * randomly chosen name is created.
79 * @param len The length of the canonical node name or -1, if the name
80 * is a zero-terminated char-string.
81 */
82 Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
83
84 /**
85 * Destroys the node. Before destruction some pre-conditions
86 * must be met:<br />
87 *
88 * 1. The node is not part of any SpoVNet <br />
89 * 2. All listeners must be unbound from this node <br />
90 * 3. The module has been stopped<br />
91 */
92 ~Node();
93
94 //--- node control ---
95
96 /**
97 * This method instructs the node to join a particular spovnet.
98 * Callees may bind with a NodeListener to receive events, when
99 * a node has been successfully joined.
100 *
101 * @param vnetId The SpoVNet name
102 */
103 void join(const Name& name);
104
105 /**
106 * This method initiates a new SpoVNet with the given SpoVNetID and
107 * parameters.
108 *
109 * @param name The SpoVNet name
110 * @param param The SpoVNet properties
111 */
112 void initiate(const Name& name, const SpoVNetProperties& parm =
113 SpoVNetProperties::DEFAULT);
114
115 /**
116 * This method initiates the leave procedure of this node.
117 */
118 void leave();
119
120 /**
121 * This method is used to bind a node listener to this node.
122 *
123 * @param listener The node listener
124 * @return boolean indicating success of failure
125 */
126 bool bind(NodeListener* listener);
127
128 /**
129 * This method is used to unbind a node listener to this node.
130 *
131 * @param listener The node listener
132 * @return boolean indicating success of failure
133 */
134 bool unbind(NodeListener* listener);
135
136 //--- spovnet properties ---
137
138 /**
139 * Returns the properties of the spovnet the node has joined.
140 *
141 * @return The properties of the spovnet the node has joined
142 */
143 const SpoVNetProperties& getSpoVNetProperties() const;
144
145 /**
146 * Returns the spovnet identifier
147 *
148 * @return The spovnet idenfifier
149 */
150 const SpoVNetID& getSpoVNetId() const;
151
152 /**
153 * Returns true, if the node is part of a spovnet.
154 *
155 * @return True, if the node is part of a spovnet
156 */
157 bool isJoined() const;
158
159 //--- addressing ---
160
161 /**
162 * Returns the node id of this node if the link id is unspecified or
163 * the node id of the remote node.
164 *
165 * @return The local or the remote node identifier
166 */
167 const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
168
169 /**
170 * Returns the node id to a node name according to the currently joined
171 * spovnet (usually derives a node identifier by hashing the name).
172 *
173 * @return The node identifier to the given name
174 */
175 NodeID generateNodeId(const Name& name) const;
176
177 /**
178 * Returns the name of this node if the link id is unspecified or
179 * the node name of the remote node, if known -- otherwise it returns
180 * an unspecified name.
181 *
182 * TODO: RFE -- send request to remote node and inform service.
183 *
184 * @return A node's name or an unspecified name, if unknown
185 */
186 const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
187
188 /**
189 * Get a list of neighboring nodes in the overlay structure.
190 * The number and identities of nodes depends highly on the
191 * used overlay structure.
192 *
193 * @return a list of NodeIDs that are neighbors in the overlay structure
194 * @see sendBroadcastMessage
195 */
196 vector<NodeID> getNeighborNodes() const;
197
198 //--- communication ---
199
200 /**
201 * Establishes a new link to another node and service with the given
202 * link properties. An optional message could be sent with the request.
203 *
204 * @param nid The remote node identifier
205 * @param sid The remote service identifier
206 * @param req The required link properties
207 * @param msg An optional message that is sent with the request
208 * @return A new link id
209 */
210 LinkID establishLink(const NodeID& nid, const ServiceID& sid,
211 const LinkProperties& req = LinkProperties::DEFAULT,
212 const DataMessage& msg = DataMessage::UNSPECIFIED);
213
214 /**
215 * This method drops an established link.
216 *
217 * @param lnk The link identifier of an active link
218 */
219 void dropLink(const LinkID& lnk);
220
221 // message sending
222
223 /**
224 * Sends a one-shot message to a service. If link properties are specified,
225 * the node tries to fulfill those requirements. This may cause the node
226 * to first establish a temporary link, second sending the message and last
227 * dropping the link. This would result in a small amount of extra latency
228 * until the message is delivered. If reliable transport was selected,
229 * the method returns a sequence number and a communication event is
230 * triggered on message delivery or loss.
231 *
232 * @param msg The message to be sent
233 * @param nid The remote node identifier
234 * @param sid The remote service identifier
235 * @param req The requirements associated with the message
236 * @return A sequence number
237 */
238 seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
239 const LinkProperties& req = LinkProperties::DEFAULT);
240
241 /**
242 * Sends a message via an established link. If reliable transport was
243 * selected, the method returns a sequence number and a communication event
244 * is triggered on message delivery or loss.
245 *
246 * @param msg The message to be sent
247 * @param lnk The link to be used for sending the message
248 */
249 seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
250
251 /**
252 * Sends a message to all known hosts in the overlay structure
253 * the nodes that are reached here depend on the overlay structure.
254 *
255 * @param msg The message to be send
256 * @param sid The id of the service that should receive the message
257 * @see getNeighborNodes
258 */
259 void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
260
261 // --- communication listeners ---
262
263 /**
264 * Binds a listener to a specifed service identifier.
265 * Whenever a link is established/dropped or messages are received the
266 * events inside the interface are called.
267 *
268 * @param listener The listener to be registered
269 * @param sid The service identifier
270 * @return boolean indicating success of failure
271 */
272 bool bind(CommunicationListener* listener, const ServiceID& sid);
273
274 /**
275 * Un-binds a listener from this node.
276 *
277 * @param The listener to be unbound
278 * @return boolean indicating success of failure
279 */
280 bool unbind(CommunicationListener* listener, const ServiceID& sid);
281
282 // --- extension proposal: service directory --
283 // main-idea: use this methods to register groups/rendevous points inside
284 // the base overlay via a distributed storage service.
285 //
286 //void put(const KeyID& key, Message* value);
287 //void get(const KeyID& key);
288 //-------------------------------------------------------------------------
289 //
290 // --- optimization proposal: allow direct endpoint descriptor exchange ---
291 // main-idea: directly allow exchanging endpoint descriptors to establish
292 // links. Depending on the overlay structure used in the base overlay, this
293 // allows a node to directly establish links between two nodes when an
294 // endpoint descriptor is known.
295 //
296 //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
297 //void sendMessage( EndpointDescriptor& epd, Message* msg );
298 //LinkID setupLink( const EndpointDescriptor& endpointDesc,
299 // const LinkProperties& req = LinkProperties::UNSPECIFIED,
300 // const Message* msg = NULL );
301 //
302 //-------------------------------------------------------------------------
303
304 // --- module implementation ---
305 //
306 // main-idea: use module properties to configure nodeid, spovnetid etc. and
307 // select start/stop procedures. This allows simulations to start a
308 // node without manually calling join etc.
309
310 /** @see Module.h */
311 void initialize();
312
313 /** @see Module.h */
314 void start();
315
316 /** @see Module.h */
317 void stop();
318
319 /** @see Module.h */
320 string getName() const;
321
322 /** @see Module.h */
323 void setProperty(string key, string value);
324
325 /** @see Module.h */
326 const string getProperty(string key) const;
327
328 /** @see Module.h */
329 const vector<string> getProperties() const;
330
331protected:
332 // friends
333 friend class AribaModule;
334
335 // member variables
336 Name name; //< node name
337 AribaModule& ariba_mod; //< ariba module
338 SpoVNetID spovnetId; //< current spovnet id
339 NodeID nodeId; //< current node id
340 overlay::BaseOverlay* base_overlay; //< the base overlay
341};
342
343} // namespace ariba
344
345#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.