An Overlay-based
Virtual Network Substrate
SpoVNet

source: source/ariba/Node.h @ 10653

Last change on this file since 10653 was 10653, checked in by Michael Tänzer, 10 years ago

Merge the ASIO branch back into trunk

File size: 10.3 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 <iostream>
52#include <boost/foreach.hpp>
53#include "Module.h"
54#include "Identifiers.h"
55#include "SpoVNetProperties.h"
56#include "NodeListener.h"
57#include "Name.h"
58#include "AribaModule.h"
59#include "CommunicationListener.h"
60#include "DataMessage.h"
61#include "SideportListener.h"
62
63using std::vector;
64using ariba::overlay::BaseOverlay;
65
66namespace ariba {
67
68/**
69 * \addtogroup public
70 * @{
71 *
72 * This class should implement all ariba node functionality.
73 *
74 * @author Sebastian Mies <mies@tm.uka.de>
75 * @author Christoph Mayer <mayer@tm.uka.de>
76 */
77class Node: public Module {
78public:
79        /**
80         * Constructs a new node using a given ariba module
81         *
82         * @param ariba_mod The ariba module
83         * @param name The canonical node name of the new node. When NULL a
84         *   randomly chosen name is created.
85         * @param len The length of the canonical node name or -1, if the name
86         *   is a zero-terminated char-string.
87         */
88        Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
89
90        /**
91         * Destroys the node. Before destruction some pre-conditions
92         * must be met:<br />
93         *
94         * 1. The node is not part of any SpoVNet <br />
95         * 2. All listeners must be unbound from this node <br />
96         * 3. The module has been stopped<br />
97         */
98        virtual ~Node();
99
100        //--- node control ---
101
102        /**
103         * This method instructs the node to join a particular spovnet.
104         * Callees may bind with a NodeListener to receive events, when
105         * a node has been successfully joined.
106         *
107         * @param vnetId The SpoVNet name
108         */
109        void join(const Name& name);
110
111        /**
112         * This method initiates a new SpoVNet with the given SpoVNetID and
113         * parameters.
114         *
115         * @param name The SpoVNet name
116         * @param param The SpoVNet properties
117         */
118        void initiate(const Name& name, const SpoVNetProperties& parm =
119                        SpoVNetProperties::DEFAULT);
120
121        /**
122         * This method initiates the leave procedure of this node.
123         */
124        void leave();
125
126        /**
127         * This method is used to bind a node listener to this node.
128         *
129         * @param listener The node listener
130         * @return boolean indicating success of failure
131         */
132        bool bind(NodeListener* listener);
133
134        /**
135         * This method is used to unbind a node listener to this node.
136         *
137         * @param listener The node listener
138         * @return boolean indicating success of failure
139         */
140        bool unbind(NodeListener* listener);
141
142        //--- spovnet properties ---
143
144        /**
145         * Returns the properties of the spovnet the node has joined.
146         *
147         * @return The properties of the spovnet the node has joined
148         */
149        const SpoVNetProperties& getSpoVNetProperties() const;
150
151        /**
152         * Returns the spovnet identifier
153         *
154         * @return The spovnet idenfifier
155         */
156        const SpoVNetID& getSpoVNetId() const;
157
158        /**
159         * Returns true, if the node is part of a spovnet.
160         *
161         * @return True, if the node is part of a spovnet
162         */
163        bool isJoined() const;
164
165        //--- addressing ---
166
167        /**
168         * Returns the node id of this node if the link id is unspecified or
169         * the node id of the remote node.
170         *
171         * @return The local or the remote node identifier
172         */
173        const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
174
175        /**
176         * Returns the node id to a node name according to the currently joined
177         * spovnet (usually derives a node identifier by hashing the name).
178         *
179         * @return The node identifier to the given name
180         */
181        NodeID generateNodeId(const Name& name) const;
182
183        /**
184         * Returns the name of this node if the link id is unspecified or
185         * the node name of the remote node, if known -- otherwise it returns
186         * an unspecified name.
187         *
188         * @return A node's name or an unspecified name, if unknown
189         */
190        const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
191
192        /**
193         * Get a list of neighboring nodes in the overlay structure.
194         * The number and identities of nodes depends highly on the
195         * used overlay structure.
196         *
197         * @return a list of NodeIDs that are neighbors in the overlay structure
198         * @see sendBroadcastMessage
199         */
200        vector<NodeID> getNeighborNodes() const;
201
202        //--- communication ---
203
204        /**
205         * Establishes a new link to another node and service with the given
206         * link properties. An optional message could be sent with the request.
207         *
208         * @param nid The remote node identifier
209         * @param sid The remote service identifier
210         * @param req The required link properties
211         * @param msg An optional message that is sent with the request
212         * @return A new link id
213         */
214        LinkID establishLink(const NodeID& nid, const ServiceID& sid);
215
216        /**
217         * This method drops an established link.
218         *
219         * @param lnk The link identifier of an active link
220         */
221        void dropLink(const LinkID& lnk);
222
223        // message sending
224
225        /**
226         * Sends a one-shot message to a service. If link properties are specified,
227         * the node tries to fulfill those requirements. This may cause the node
228         * to first establish a temporary link, second sending the message and last
229         * dropping the link. This would result in a small amount of extra latency
230         * until the message is delivered. If reliable transport was selected,
231         * the method returns a sequence number and a communication event is
232         * triggered on message delivery or loss.
233         *
234         * @param msg The message to be sent
235         * @param nid The remote node identifier
236         * @param sid The remote service identifier
237         * @param req The requirements associated with the message
238         * @return A sequence number
239         */
240        seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
241                        const LinkProperties& req = LinkProperties::DEFAULT);
242
243        /**
244         * like the above function, but sends the message to the closest directly known node
245         * to the specified address
246         */
247    NodeID sendMessageCloserToNodeID(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
248            const LinkProperties& req = LinkProperties::DEFAULT);
249
250        /**
251         * Sends a message via an established link. If reliable transport was
252         * selected, the method returns a sequence number and a communication event
253         * is triggered on message delivery or loss.
254         *
255         * @param msg The message to be sent
256         * @param lnk The link to be used for sending the message
257         */
258        seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
259
260        /**
261         * Sends a message to all known hosts in the overlay structure
262         * the nodes that are reached here depend on the overlay structure.
263         *
264         * @param msg The message to be send
265         * @param sid The id of the service that should receive the message
266         * @see getNeighborNodes
267         */
268        void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
269
270        // --- communication listeners ---
271
272        /**
273         * Binds a listener to a specifed service identifier.
274         * Whenever a link is established/dropped or messages are received the
275         * events inside the interface are called.
276         *
277         * @param listener The listener to be registered
278         * @param sid The service identifier
279         * @return boolean indicating success of failure
280         */
281        bool bind(CommunicationListener* listener, const ServiceID& sid);
282
283        /**
284         * Un-binds a listener from this node.
285         *
286         * @param The listener to be unbound
287         * @return boolean indicating success of failure
288         */
289        bool unbind(CommunicationListener* listener, const ServiceID& sid);
290
291        //-------------------------------------------------------------------------
292        //
293        // --- optimization proposal: allow direct endpoint descriptor exchange ---
294        // main-idea: directly allow exchanging endpoint descriptors to establish
295        // links. Depending on the overlay structure used in the base overlay, this
296        // allows a node to directly establish links between two nodes when an
297        // endpoint descriptor is known.
298        //
299        //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
300        //void sendMessage( EndpointDescriptor& epd, Message* msg );
301        //LinkID setupLink( const EndpointDescriptor& endpointDesc,
302        //              const LinkProperties& req = LinkProperties::UNSPECIFIED,
303        //              const Message* msg = NULL );
304        //
305        //-------------------------------------------------------------------------
306
307        // --- module implementation ---
308        //
309        // main-idea: use module properties to configure nodeid, spovnetid etc. and
310        // select start/stop procedures. This allows simulations to start a
311        // node without manually calling join etc.
312
313        /** @see Module.h */
314        string getName() const;
315
316protected:
317        // friends
318        friend class AribaModule;
319
320        // member variables
321        Name name;                             //< node name
322        AribaModule& ariba_mod;                //< ariba module
323        SpoVNetID spovnetId;                   //< current spovnet id
324        NodeID nodeId;                             //< current node id
325        overlay::BaseOverlay* base_overlay;    //< the base overlay
326
327};
328
329} // namespace ariba
330
331/** @} */
332
333#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.