DTN2-BPQ: comparison servlib/contacts/Link.h

equal deleted inserted replaced

--1:000000000000
+:2b3e5ec03512
+/*
+*    Copyright 2004-2006 Intel Corporation
+*
+*    Licensed under the Apache License, Version 2.0 (the "License");
+*    you may not use this file except in compliance with the License.
+*    You may obtain a copy of the License at
+*
+*        http://www.apache.org/licenses/LICENSE-2.0
+*
+*    Unless required by applicable law or agreed to in writing, software
+*    distributed under the License is distributed on an "AS IS" BASIS,
+*    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+*    See the License for the specific language governing permissions and
+*    limitations under the License.
+*/
+#ifndef _LINK_H_
+#define _LINK_H_
+#include <set>
+#include <oasys/debug/Formatter.h>
+#include <oasys/serialize/Serialize.h>
+#include <oasys/thread/SpinLock.h>
+#include <oasys/util/Ref.h>
+#include <oasys/util/RefCountedObject.h>
+#include "bundling/BundleList.h"
+#include "naming/EndpointID.h"
+#include "Contact.h"
+#include "NamedAttribute.h"
+namespace dtn {
+class ConvergenceLayer;
+class CLInfo;
+class Contact;
+class Link;
+class RouterInfo;
+/**
+* Typedef for a reference on a link.
+*/
+typedef oasys::Ref<Link> LinkRef;
+/**
+* Set of links
+*/
+class LinkSet : public std::set<LinkRef> {};
+/**
+* Abstraction for a DTN link, i.e. a one way communication channel to
+* a next hop node in the DTN overlay.
+*
+* The state of a link (regarding its availability) is described by
+* the Link::state_t enumerated type.
+*
+* All links in the OPEN state have an associated contact that
+* represents an actual connection.
+*
+* Every link has a unique name associated with it which is used to
+* identify it. The name is configured explicitly when the link is
+* created.
+*
+* Creating new links:
+* Links are created explicitly in the configuration file. Syntax is:
+* @code
+* link add <name> <nexthop> <type> <conv_layer> <args>
+* @endcode
+* See servlib/cmd/LinkCommand.cc for implementation of this TCL cmd.
+*
+* ----------------------------------------------------------
+*
+* Links are of three types as discussed in the DTN architecture
+* ONDEMAND, SCHEDULED, OPPORTUNISTIC.
+*
+* The key differences from an implementation perspective are "who"
+* and "when" manipulates the link state regarding availability.
+*
+* ONDEMAND links are initializd in the AVAILABLE state, as one would
+* expect. It remains in this state until a router explicitly opens
+* it.
+*
+* An ONDEMAND link can then be closed either due to connection
+* failure or because the link has been idle for too long, both
+* triggered by the convergence layer. If an ONDEMAND link is closed
+* due to connection failure, then the contact manager is notified of
+* this event and periodically tries to re-establish the link.
+*
+* For OPPORTUNISTIC links the availability state is set by the code
+* which detects that there is a new link available to be used.
+*
+* SCHEDULED links have their availability dictated by the schedule
+* implementation.
+*
+* ----------------------------------------------------------
+*
+* Links are used for input and/or output. In other words, for
+* connection-oriented convergence layers like TCP, a link object is
+* created whenever a new connection is made to a peer or when a
+* connection arrives from a peer.
+*/
+class Link : public oasys::RefCountedObject,
+public oasys::Logger,
+public oasys::SerializableObject {
+public:
+/**
+* Valid types for a link.
+*/
+typedef enum
+{
+LINK_INVALID = -1,
+/**
+* The link is expected to be ALWAYS available, and any
+* convergence layer connection state is always maintained for
+* it.
+*/
+ALWAYSON = 1,
+/**
+* The link is expected to be either always available, or can
+* be made available easily. Examples include DSL (always),
+* and dialup (easily available). Convergence layers are free
+* to tear down idle connection state, but are expected to be
+* able to easily re-establish it.
+*/
+ONDEMAND = 2,
+/**
+* The link is only available at pre-determined times.
+*/
+SCHEDULED = 3,
+/**
+* The link may or may not be available, based on
+* uncontrollable factors. Examples include a wireless link
+* whose connectivity depends on the relative locations of the
+* two nodes.
+*/
+OPPORTUNISTIC = 4
+}
+link_type_t;
+/**
+* Link type string conversion.
+*/
+static inline const char*
+link_type_to_str(link_type_t type)
+{
+switch(type) {
+case ALWAYSON:		return "ALWAYSON";
+case ONDEMAND:		return "ONDEMAND";
+case SCHEDULED:		return "SCHEDULED";
+case OPPORTUNISTIC: 	return "OPPORTUNISTIC";
+default: 		PANIC("bogus link_type_t");
+}
+}
+static inline link_type_t
+str_to_link_type(const char* str)
+{
+if (strcasecmp(str, "ALWAYSON") == 0)
+return ALWAYSON;
+if (strcasecmp(str, "ONDEMAND") == 0)
+return ONDEMAND;
+if (strcasecmp(str, "SCHEDULED") == 0)
+return SCHEDULED;
+if (strcasecmp(str, "OPPORTUNISTIC") == 0)
+return OPPORTUNISTIC;
+return LINK_INVALID;
+}
+/**
+* The possible states for a link. These are defined as distinct
+* bitfield values so that various functions can match on a set of
+* states (e.g. see ContactManager::find_link_to).
+*/
+typedef enum {
+UNAVAILABLE = 1,///< The link is closed and not able to be
+///  opened currently.
+AVAILABLE = 2,	///< The link is closed but is able to be
+///  opened, either because it is an on demand
+///  link, or because an opportunistic peer
+///  node is in close proximity but no
+///  convergence layer session has yet been
+///  opened.
+OPENING = 4,	///< A convergence layer session is in the
+///  process of being established.
+OPEN = 8,	///< A convergence layer session has been
+///  established, and the link has capacity
+///  for a bundle to be sent on it. This may
+///  be because no bundle is currently being
+///  sent, or because the convergence layer
+///  can handle multiple simultaneous bundle
+///  transmissions.
+CLOSED = 16	///< Bogus state that's never actually used in
+///  the Link state_ variable, but is used for
+///  signalling the daemon thread with a
+///  LinkStateChangeRequest
+} state_t;
+/**
+* Convert a link state into a string.
+*/
+static inline const char*
+state_to_str(state_t state)
+{
+switch(state) {
+case UNAVAILABLE: 	return "UNAVAILABLE";
+case AVAILABLE: 	return "AVAILABLE";
+case OPENING: 		return "OPENING";
+case OPEN: 		return "OPEN";
+case CLOSED: 		return "CLOSED";
+}
+NOTREACHED;
+}
+/**
+* Static function to create appropriate link object from link type.
+*/
+static LinkRef create_link(const std::string& name, link_type_t type,
+ConvergenceLayer* cl, const char* nexthop,
+int argc, const char* argv[],
+const char** invalid_argp = NULL);
+/**
+* Constructor / Destructor
+*/
+Link(const std::string& name, link_type_t type,
+ConvergenceLayer* cl, const char* nexthop);
+/**
+* Constructor for unserialization.
+*/
+Link(const oasys::Builder& b);
+/**
+* Handle and mark deleted link.
+*/
+virtual void delete_link();
+/**
+* Reconfigure the link parameters.
+*/
+virtual bool reconfigure_link(int argc, const char* argv[]);
+virtual void reconfigure_link(AttributeVector& params);
+/**
+* Virtual from SerializableObject
+*/
+void serialize(oasys::SerializeAction* action);
+/**
+* Hook for subclass to parse arguments.
+*/
+virtual int parse_args(int argc, const char* argv[],
+const char** invalidp = NULL);
+/**
+* Hook for subclass to post events to control the initial link
+* state, after all initialization is complete.
+*/
+virtual void set_initial_state();
+/**
+* Return the type of the link.
+*/
+link_type_t type() const { return static_cast<link_type_t>(type_); }
+/**
+* Return the string for of the link.
+*/
+const char* type_str() const { return link_type_to_str(type()); }
+/**
+* Return whether or not the link is open.
+*/
+bool isopen() const { return ( (state_ == OPEN) ); }
+/**
+* Return the availability state of the link.
+*/
+bool isavailable() const { return (state_ != UNAVAILABLE); }
+/**
+* Return whether the link is in the process of opening.
+*/
+bool isopening() const { return (state_ == OPENING); }
+/**
+* Returns true if the link has been deleted; otherwise returns false.
+*/
+bool isdeleted() const;
+/**
+* Return the actual state.
+*/
+state_t state() const { return static_cast<state_t>(state_); }
+/**
+* Sets the state of the link. Performs various assertions to
+* ensure the state transitions are legal.
+*
+* This function should only ever be called by the main
+* BundleDaemon thread and helper classes. All other threads must
+* use a LinkStateChangeRequest event to cause changes in the link
+* state.
+*
+* The function isn't protected since some callers (i.e.
+* convergence layers) are not friend classes but some functions
+* are run by the BundleDaemon thread.
+*/
+void set_state(state_t state);
+/**
+* Set/get the create_pending_ flag on the link.
+*/
+void set_create_pending(bool create_pending = true)
+{ create_pending_ = create_pending; }
+bool is_create_pending() const { return create_pending_; }
+/**
+* Set/get the usable_ flag on the link.
+*/
+void set_usable(bool usable = true) { usable_ = usable; }
+bool is_usable() const { return usable_; }
+/**
+* Return the current contact information (if any).
+*/
+const ContactRef& contact() const { return contact_; }
+/**
+* Set the contact information.
+*/
+void set_contact(Contact* contact)
+{
+// XXX/demmer check this invariant
+ASSERT(contact_ == NULL);
+contact_ = contact;
+}
+/**
+* Store convergence layer state associated with the link.
+*/
+void set_cl_info(CLInfo* cl_info)
+{
+ASSERT((cl_info_ == NULL && cl_info != NULL) ||
+(cl_info_ != NULL && cl_info == NULL));
+cl_info_ = cl_info;
+}
+/**
+* Accessor to the convergence layer state.
+*/
+CLInfo* cl_info() const { return cl_info_; }
+/**
+* Store router state associated with the link.
+*/
+void set_router_info(RouterInfo* router_info)
+{
+ASSERT((router_info_ == NULL && router_info != NULL) ||
+(router_info_ != NULL && router_info == NULL));
+router_info_ = router_info;
+}
+/**
+* Accessor to the convergence layer state.
+*/
+RouterInfo* router_info() const { return router_info_; }
+/**
+* Accessor to this contact's convergence layer.
+*/
+ConvergenceLayer* clayer() const { return clayer_; }
+/**
+* Accessor to this links name
+*/
+const char* name() const { return name_.c_str(); }
+/**
+* Accessor to this links name as a c++ string
+*/
+const std::string& name_str() const { return name_; }
+/**
+* Accessor to next hop string
+*/
+const char* nexthop() const { return nexthop_.c_str(); }
+/**
+* Accessor to next hop string
+*/
+const std::string& nexthop_str() const { return nexthop_; }
+/**
+* Override for the next hop string.
+*/
+void set_nexthop(const std::string& nexthop) { nexthop_.assign(nexthop); }
+/**
+* Accessor to the reliability bit.
+*/
+bool is_reliable() const { return reliable_; }
+/**
+* Accessor to set the reliability bit when the link is created.
+*/
+void set_reliable(bool r) { reliable_ = r; }
+/**
+* Accessor to set the remote endpoint id.
+*/
+void set_remote_eid(const EndpointID& remote) {
+remote_eid_.assign(remote);
+}
+/**
+* Accessor to the remote endpoint id.
+*/
+const EndpointID& remote_eid() { return remote_eid_; }
+/**
+* Accessor for the link's queue of bundles that are awaiting
+* transmission.
+*/
+const BundleList* queue() { return &queue_; }
+/**
+* Return whether or not the queue is full, based on the
+* configured queue limits.
+*/
+bool queue_is_full() const;
+/**
+* Return whether or not the queue has space, based on the
+* configured queue limits.
+*/
+bool queue_has_space() const;
+/**
+* Accessor for the link's list of bundles that have been
+* transmitted but for which the convergence layer is awaiting
+* acknowledgement.
+*/
+const BundleList* inflight() { return &inflight_; }
+/// @{
+/**
+* Accessor functions to add/remove bundles from the link queue
+* and inflight list, keeping the statistics in-sync with the
+* state of the lists.
+*/
+bool add_to_queue(const BundleRef& bundle, size_t total_len);
+bool del_from_queue(const BundleRef& bundle, size_t total_len);
+bool add_to_inflight(const BundleRef& bundle, size_t total_len);
+bool del_from_inflight(const BundleRef& bundle, size_t total_len);
+/// @}
+/**
+* Virtual from formatter
+*/
+int format(char* buf, size_t sz) const;
+/**
+* Debugging printout.
+*/
+void dump(oasys::StringBuffer* buf);
+/**************************************************************
+* Link Parameters
+*/
+struct Params {
+/**
+* Default constructor.
+*/
+Params();
+/**
+* MTU of the link, used to control proactive fragmentation.
+*/
+u_int mtu_;
+/**
+* Minimum amount to wait between attempts to re-open the link
+* (in seconds).
+*
+* Default is set by the various Link types but can be overridden
+* by configuration parameters.
+*/
+u_int min_retry_interval_;
+/**
+* Maximum amount to wait between attempts to re-open the link
+* (in seconds).
+*
+* Default is set by the various Link types but can be overridden
+* by configuration parameters.
+*/
+u_int max_retry_interval_;
+/**
+* Seconds of idle time before the link is closed. Must be
+* zero for always on links (i.e. they are never closed).
+*
+* Default is 30 seconds for on demand links, zero for
+* opportunistic links.
+*/
+u_int idle_close_time_;
+/**
+* Conservative estimate of the maximum amount of time that
+* the link may be down during "normal" operation. Used by
+* routing algorithms to determine how long to leave bundles
+* queued on the down link before rerouting them. Fefault is
+* 30 seconds.
+*/
+u_int potential_downtime_;
+/**
+* Whether or not to send the previous hop header on this
+* link. Default is false.
+*/
+bool prevhop_hdr_;
+/**
+* Abstract cost of the link, used by routing algorithms.
+* Default is 100.
+*/
+u_int cost_;
+/** @{
+*
+* Configurable high / low limits on the number of
+* bundles/bytes that should be queued on the link.
+*
+* The high limits are used by Link::is_queue_full() to
+* indicate whether or not more bundles can be queued onto the
+* link to effect backpressure from the convergence layers.
+*
+* The low limits can be used by the router to determine when
+* to re-scan the pending bundle lists
+*/
+u_int     qlimit_bundles_high_;
+u_int64_t qlimit_bytes_high_;
+u_int     qlimit_bundles_low_;
+u_int64_t qlimit_bytes_low_;
+/// @}
+};
+/**
+* Seconds to wait between attempts to re-open an unavailable
+* link. Initially set to min_retry_interval_, then doubles up to
+* max_retry_interval_.
+*/
+u_int retry_interval_;
+/**
+* Accessor for the parameter structure.
+*/
+const Params& params() const { return params_; }
+Params& params() { return params_; }
+/*************************************************************
+* Link Statistics
+*/
+struct Stats {
+/**
+* Number of times the link attempted to be opened.
+*/
+u_int contact_attempts_;
+/**
+* Number of contacts ever successfully opened on the link
+* (equivalent to the number of times the link was open)
+*/
+u_int contacts_;
+/**
+* Number of bundles transmitted over the link.
+*/
+u_int bundles_transmitted_;
+/**
+* Total byte count transmitted over the link.
+*/
+u_int bytes_transmitted_;
+/**
+* Number of bundles with cancelled transmission.
+*/
+u_int bundles_cancelled_;
+/**
+* The total uptime of the link, not counting the current
+* contact.
+*/
+u_int uptime_;
+/**
+* The availablity of the link, as measured over time by the
+* convergence layer.
+*/
+u_int availability_;
+/**
+* The reliability of the link, as measured over time by the
+* convergence layer.  This is different from the is_reliable
+* setting, which indicates whether the convergence layer should
+* expect acks from the peer.
+*/
+u_int reliability_;
+};
+/**
+* Accessor for the stats structure.
+*/
+Stats* stats() { return &stats_; }
+/**
+* Reset the stats.
+*/
+void reset_stats() const
+{
+memset(&stats_, 0, sizeof(stats_));
+}
+/**
+* Dump a printable version of the stats.
+*/
+void dump_stats(oasys::StringBuffer* buf);
+/// @{ Accessors for the link queue stats
+u_int bundles_queued()   { return bundles_queued_; }
+u_int bytes_queued()     { return bytes_queued_; }
+u_int bundles_inflight() { return bundles_inflight_; }
+u_int bytes_inflight()   { return bytes_inflight_; }
+/// @}
+/**
+* Accessor for the Link state lock.
+*/
+oasys::Lock* lock() { return &lock_; }
+protected:
+friend class BundleActions;
+friend class BundleDaemon;
+friend class ContactManager;
+friend class ParamCommand;
+/**
+* Open the link. Protected to make sure only the friend
+* components can call it and virtual to allow subclasses to
+* override it.
+*/
+virtual void open();
+/**
+* Close the link. Protected to make sure only the friend
+* components can call it and virtual to allow subclasses to
+* override it.
+*/
+virtual void close();
+/// Type of the link
+int type_;
+/// State of the link
+u_int32_t state_;
+/// Flag, that when set to true, indicates that the link has been deleted.
+bool deleted_;
+/// Flag, that when set to true, indicates that the creation of the
+/// link is pending; the convergence layer will post a creation event
+/// when the creation is complete. While creation is pending, the
+/// link cannot be opened nor can bundles be queued for it.
+bool create_pending_;
+/// Flag, that when set to true, indicates that the link is allowed
+/// to be used to transmit bundles.
+bool usable_;
+/// Next hop address
+std::string nexthop_;
+/// Internal name of the link
+std::string name_;
+/// Whether or not this link is reliable
+bool reliable_;
+/// Parameters of the link
+Params params_;
+/// Default parameters of the link
+static Params default_params_;
+/// Lock to protect internal data structures and state.
+oasys::SpinLock lock_;
+/// Queue of bundles currently active or pending transmission on the Link
+BundleList queue_;
+/// Queue of bundles that have been sent but not yet acknowledged
+BundleList inflight_;
+/** @{
+*
+* Data counters about the link queues, both in terms of bundles
+* and bytes.
+*
+*    *_queued:       the link queue size
+*    *_inflight:     transmitted but not yet acknowledged
+*/
+u_int bundles_queued_;
+u_int bytes_queued_;
+u_int bundles_inflight_;
+u_int bytes_inflight_;
+/** @} */
+/// Stats for the link
+mutable Stats stats_;
+/// Current contact. contact_ != null iff link is open
+ContactRef contact_;
+/// Pointer to convergence layer
+ConvergenceLayer* clayer_;
+/// Convergence layer specific info, if needed
+CLInfo* cl_info_;
+/// Router specific info, if needed
+RouterInfo* router_info_;
+/// Remote's endpoint ID (eg, dtn://hostname.dtn)
+EndpointID remote_eid_;
+/// Destructor -- protected since links shouldn't be deleted
+virtual ~Link();
+};
+} // namespace dtn
+#endif /* _LINK_H_ */