senf/PPI/Route.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Route public header */
  25
  26 #ifndef HH_SENF_PPI_Route_
  27 #define HH_SENF_PPI_Route_ 1
  28
  29 // Custom includes
  30 #include <boost/type_traits.hpp>
  31 #include "predecl.hh"
  32
  33 //#include "Route.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37 namespace ppi {
  38
  39     /** \brief Routing base class
  40
  41         Routing information is defined within each module to define the control flow. RouteBase is
  42         the generic base class for all routing entries.
  43      */
  44     class RouteBase
  45     {
  46     public:
  47         virtual ~RouteBase();
  48
  49 #ifdef DOXYGEN
  50         Source & source() const;        ///< Routing source
  51                                         /**< \note The real implementation is in the \c
  52                                              BaseRouteImplementation template in \c Route.ih. This
  53                                              class is internal and not documented. */
  54         Target & target() const;        ///< Routing target
  55                                         /**< \note The real implementation is in the \c
  56                                              BaseRouteImplementation template in \c Route.ih. This
  57                                              class is internal and not documented. */
  58 #endif
  59
  60         bool hasConnector(connector::Connector const & conn) const;
  61                                         ///< \c true, if route has connector \a conn
  62         bool hasEvent(EventDescriptor const & event) const;
  63                                         ///< \c true, if route has event \a event
  64
  65     protected:
  66         RouteBase(module::Module & module);
  67
  68     private:
  69         virtual bool v_hasConnector(connector::Connector const & conn) const = 0;
  70         virtual bool v_hasEvent(EventDescriptor const & event) const = 0;
  71
  72         module::Module * module_;
  73     };
  74
  75     /** \brief Forwarding route base class
  76
  77         All routes which may forward control information are based on
  78         ForwardingRoute. ForwardingRoute provides methods to control and query the throttling
  79         behavior.
  80      */
  81     class ForwardingRoute
  82         : public RouteBase
  83     {
  84     public:
  85         bool autoThrottling() const;    ///< Query current autoThrottling state
  86         void autoThrottling(bool state); ///< Change automatic throttle notification forwarding
  87                                         /**< By default, throttle notifications are automatically
  88                                              forwarded from active to passive connectors. This may
  89                                              be disabled by setting the authoThrottling state to \c
  90                                              false.
  91
  92                                              Routing from/to an event to/from a passive connector
  93                                              will automatically create throttling notifications on
  94                                              the connector whenever the event is disabled. Routing
  95                                              form/to an event to/from an active connector will
  96                                              disable the event whenever a throttling notification
  97                                              comes in. Respective for unthrottle notifications.
  98
  99                                              \param[in] state New throttle forwarding state */
 100
 101         bool throttled() const;         ///< \c true, if the route is throttled
 102                                         /**< This member checks only the automatic throttling
 103                                              state. If autoThrottling() is \c false, this member
 104                                              will always return \c false. */
 105
 106     protected:
 107         ForwardingRoute(module::Module & module);
 108
 109         // Called to register this route with the connectors forwarding information base
 110         template <class T> void registerRoute(T & ob);
 111         template <class T> void unregisterRoute(T & ob);
 112
 113         template <class T> void notifyThrottle(T & ob);
 114         template <class T> void notifyUnthrottle(T & ob);
 115
 116     private:
 117         // called to forward a throttling notification along the route
 118         void notifyThrottle();
 119         void notifyUnthrottle();
 120
 121         // Implemented in the derived classes to forward throttling notifications
 122         virtual void v_notifyThrottle() = 0;
 123         virtual void v_notifyUnthrottle() = 0;
 124         virtual bool v_throttled() const = 0;
 125
 126         bool autoThrottling_;
 127
 128         friend class connector::ActiveConnector;
 129     };
 130
 131 }}
 132
 133 // We need detail::RouteImplementation here ...
 134 #include "Route.ih"
 135
 136 namespace senf {
 137 namespace ppi {
 138
 139     /** \brief Route descriptor
 140
 141         Route instances are created by Module::route statements. The Route class provides an
 142         interface to manipulate the flow processing.
 143
 144         Depending on the type of route, one of the following classes will be a baseclass:
 145
 146         <dl> <dt>ForwardingRoute</dt><dd>If the route is a \e forwarding route. This is a route
 147         which forwards throttling notifications. This is the case, if one of the route endpoints is
 148         a notify source (a connector::ActiveConnector) and the other is a
 149         notify target (a connector::PassiveConnector or an EventDescriptor).
 150
 151         <dt>RouteBase</dt><dd>If the route is not a forwarding route, it is based directly on the
 152         generic route base class</dd></dl>
 153      */
 154     template <class Source, class Target>
 155     class Route
 156         : public detail::RouteImplementation<Source,Target>
 157     {
 158     private:
 159         typedef detail::RouteImplementation<Source,Target> Base;
 160         typedef detail::RouteImplementation<Source,Target> Implementation;
 161
 162         Route(module::Module & module, Source & source, Target & target);
 163
 164         friend class module::Module;
 165     };
 166
 167 }}
 168
 169 ///////////////////////////////hh.e////////////////////////////////////////
 170 #include "Route.cci"
 171 #include "Route.ct"
 172 #include "Route.cti"
 173 #endif
 174
 175 \f
 176 // Local Variables:
 177 // mode: c++
 178 // fill-column: 100
 179 // c-file-style: "senf"
 180 // indent-tabs-mode: nil
 181 // ispell-local-dictionary: "american"
 182 // compile-command: "scons -u test"
 183 // comment-column: 40
 184 // End: