source: source/ariba/overlay/modules/OverlayInterface.h

Last change on this file was 12060, checked in by hock@…, 11 years ago

Reintegrate branch: 20130111-hock-message_classes

improvements:

  • new message classes (reboost, zero-copy)
  • "fast path" for direct links (skip overlay layer)
  • link-properties accessible from the application
  • SystemQueue can call boost::bind functions
  • protlib compatibility removed (32bit overhead saved in every message)
  • addressing2
  • AddressDiscovery discoveres only addresses on which we're actually listening
  • ariba serialization usage reduced (sill used in OverlayMsg)
  • Node::connect, easier and cleaner interface to start-up ariba from the application
  • ariba configs via JSON, XML, etc (boost::property_tree)
  • keep-alive overhead greatly reduced
  • (relayed) overlay links can actually be closed now
  • lost messages are detected in most cases
  • notification to the application when link is transformed into direct-link
  • overlay routing: send message to second best hop if it would be dropped otherwise
  • SequenceNumbers (only mechanisms, so for: upward compatibility)
  • various small fixes


regressions:

  • bluetooth is not yet working again
  • bootstrap modules deactivated
  • liblog4xx is not working (use cout-logging)

This patch brings great performance and stability improvements at cost of backward compatibility.
Also bluetooth and the bootstrap modules have not been ported to the new interfaces, yet.

File size: 7.1 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 ARIBA PROJECT 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 __OVERLAY_INTERFACE_H
40#define __OVERLAY_INTERFACE_H
41
42#include "ariba/CommunicationListener.h"
43#include "ariba/communication/EndpointDescriptor.h"
44#include "ariba/overlay/modules/OverlayStructureEvents.h"
45#include "ariba/utility/types/NodeID.h"
46#include "ariba/utility/types/ServiceID.h"
47#include "ariba/utility/types/OverlayParameterSet.h"
48
49using ariba::CommunicationListener;
50using ariba::communication::EndpointDescriptor;
51using ariba::overlay::OverlayStructureEvents;
52using ariba::utility::NodeID;
53using ariba::utility::ServiceID;
54using ariba::utility::OverlayParameterSet;
55
56namespace ariba {
57namespace overlay {
58
59class BaseOverlay;
60
61/**
62 * This class declares an interface for an structured overlay.
63 */
64class OverlayInterface: public CommunicationListener {
65 friend class BaseOverlay;
66
67public:
68 /**
69 * A node list
70 */
71 typedef vector<NodeID> NodeList;
72
73 /**
74 * Constructs a new overlay.
75 */
76 OverlayInterface( BaseOverlay& _baseoverlay, const NodeID& _nodeid,
77 OverlayStructureEvents* _eventsReceiver, OverlayParameterSet _parameters
78 );
79
80 /**
81 * Destructs the overlay.
82 */
83 virtual ~OverlayInterface();
84
85 /**
86 * Creates the overlay.
87 */
88 virtual void createOverlay() = 0;
89
90 /**
91 * Destroys the overlay.
92 */
93 virtual void deleteOverlay() = 0;
94
95 /**
96 * Joins the overlay. Starts integration and stabilization of the overlay
97 * Node.
98 *
99 * @param bootstrap The bootstrap end-point descriptor or the default
100 * end-point, if this node is the initiator
101 */
102 virtual void joinOverlay(
103 const EndpointDescriptor& bootstrap = EndpointDescriptor::UNSPECIFIED()) = 0;
104
105 /**
106 * Leaves the overlay gracefully.
107 */
108 virtual void leaveOverlay() = 0;
109
110 /**
111 * Resolves a overlay neighbor.
112 *
113 * @param node The node to resolve
114 * @return Endpoint descriptor of local neighbor or UNSPECIFIED
115 */
116 virtual const EndpointDescriptor& resolveNode(const NodeID& node) = 0;
117
118
119 /**
120 * Returns true if this is the closest node to the given node
121 * identifier.
122 *
123 * @param node The node identifier to compare with
124 * @return True if this is the closest node to the given node identifier
125 */
126 virtual bool isClosestNodeTo( const NodeID& node ) = 0;
127
128 /**
129 * Returns the nodes known to this overlay.
130 *
131 * Usually this are the direct neighbors in the overlay structure.
132 * For instance, Chord would return his predecessor, successor and finger
133 * nodes. On the other hand OneHop would likely return all participating
134 * nodes in the overlay.
135 *
136 * @return The list of all known nodes
137 */
138 virtual NodeList getKnownNodes(bool deep = true) const = 0;
139
140 /**
141 * Returns the link id of the next hop a route message would take.
142 *
143 * @param id The destination node id
144 * @return The link id of the next hop
145 */
146 virtual const LinkID& getNextLinkId( const NodeID& id ) const = 0;
147
148 /**
149 * Returns link ids of possible next hops a route message could take,
150 * sorted by "quality" (e.g. overlay-distance).
151 *
152 * The »num« parameter can be used to specify the desired number of elements
153 * in the returned vector. This is intendet for optimizations. The
154 * implementation may choose to return a different number of elements than
155 * requested.
156 *
157 * NOTE: The returned vector may contain »unspecified« links. These refer to
158 * to the own node. (e.g. If there's no closer node, the top element in the
159 * returned vector is unsoecified.)
160 *
161 * @param id The destination node id
162 * @param num The desired number of elements in the returned vector.
163 * (0 means »not specified/max)«
164 * @return A sorted vector of link ids to possible next hops.
165 */
166 virtual std::vector<const LinkID*> getSortedLinkIdsTowardsNode(
167 const NodeID& id, int num = 0 ) const = 0;
168
169 /**
170 * Returns the NodeID of the next hop a route message would take.
171 *
172 * @param id The destination node id
173 * @return The node id of the next hop
174 */
175 virtual const NodeID& getNextNodeId( const NodeID& id ) const = 0;
176
177 //--- functions from CommunicationListener that we _can_ use as overlay ---
178
179 /// @see CommunicationListener
180 virtual void onLinkUp(const LinkID& lnk, const NodeID& remote);
181
182 /// @see CommunicationListener
183 virtual void onLinkDown(const LinkID& lnk, const NodeID& remote);
184
185 /// @see CommunicationListener
186 virtual void onLinkChanged(const LinkID& lnk, const NodeID& remote);
187
188 /// @see CommunicationListener
189 virtual void onLinkFail(const LinkID& lnk, const NodeID& remote);
190
191 /// @see CommunicationListener
192 virtual void onLinkQoSChanged(const LinkID& lnk, const NodeID& remote,
193 const LinkProperties& prop);
194
195 /// @see CommunicationListener
196 virtual bool onLinkRequest(const NodeID& remote, const DataMessage& msg);
197
198 /// @see CommunicationListener
199 virtual void onMessage(OverlayMsg* msg,
200 reboost::shared_buffer_t sub_msg,
201 const NodeID& remote,
202 const LinkID& lnk = LinkID::UNSPECIFIED);
203
204 const OverlayParameterSet& getParameters() const;
205
206 virtual std::string debugInformation() const;
207
208protected:
209 /// Reference to an active base overlay
210 BaseOverlay& baseoverlay;
211
212 /// The node identifier to use with this overlay
213 const NodeID& nodeid;
214
215 /// The listener used to inform about overlay structure changes
216 OverlayStructureEvents* eventsReceiver;
217
218 /// The parameters of the overlay structure
219 OverlayParameterSet parameters;
220
221 /// The service identifer of this overlay
222 static ServiceID OVERLAY_SERVICE_ID;
223};
224
225}} // namespace ariba, overlay
226
227#endif // __OVERLAY_INTERFACE_H
Note: See TracBrowser for help on using the repository browser.