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_Route_
  27 #define HH_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     protected:
  61         RouteBase(module::Module & module);
  62
  63     private:
  64         module::Module * module_;
  65     };
  66
  67     /** \brief Forwarding route base class
  68
  69         All routes which may forward control information are based on
  70         ForwardingRoute. ForwardingRoute provides methods to control and query the throttling
  71         behavior.
  72      */
  73     class ForwardingRoute
  74         : public RouteBase
  75     {
  76     public:
  77         bool autoThrottling() const;    ///< Query current autoThrottling state
  78         void autoThrottling(bool state); ///< Change automatic throttle notification forwarding
  79                                         /**< By default, throttle notifications are automatically
  80                                              forwarded from active to passive connectors. This may
  81                                              be disabled by setting the authoThrottling state to \c
  82                                              false.
  83
  84                                              Routing from/to an event to/from a passive connector
  85                                              will automatically create throttling notifications on
  86                                              the connector whenever the event is disabled. Routing
  87                                              form/to an event to/from an active connector will
  88                                              disable the event whenever a throttling notification
  89                                              comes in. Respective for unthrottle notifications.
  90
  91                                              \param[in] state New throttle forwarding state */
  92
  93         bool throttled() const;         ///< \c true, if the route is throttled
  94                                         /**< This member checks only the automatic throttling
  95                                              state. If autoThrottling() is \c false, this member
  96                                              will always return \c false. */
  97
  98     protected:
  99         ForwardingRoute(module::Module & module);
 100
 101         // Called to register this route with the connectors forwarding information base
 102         template <class T> void registerRoute(T & ob);
 103
 104         template <class T> void notifyThrottle(T & ob);
 105         template <class T> void notifyUnthrottle(T & ob);
 106
 107     private:
 108         // called to forward a throttling notification along the route
 109         void notifyThrottle();
 110         void notifyUnthrottle();
 111
 112         // Implemented in the derived classes to forward throttling notifications
 113         virtual void v_notifyThrottle() = 0;
 114         virtual void v_notifyUnthrottle() = 0;
 115         virtual bool v_throttled() const = 0;
 116
 117         bool autoThrottling_;
 118
 119         friend class connector::ActiveConnector;
 120     };
 121
 122 }}
 123
 124 // We need detail::RouteImplementation here ...
 125 #include "Route.ih"
 126
 127 namespace senf {
 128 namespace ppi {
 129
 130     /** \brief Route descriptor
 131
 132         Route instances are created by Module::route statements. The Route class provides an
 133         interface to manipulate the flow processing.
 134
 135         Depending on the type of route, one of the following classes will be a baseclass:
 136
 137         <dl> <dt>ForwardingRoute</dt><dd>If the route is a \e forwarding route. This is a route
 138         which forwards throttling notifications. This is the case, if one of the route endpoints is
 139         a notify source (a connector::ActiveConnector) and the other is a
 140         notify target (a connector::PassiveConnector or an EventDescriptor).
 141
 142         <dt>RouteBase</dt><dd>If the route is not a forwarding route, it is based directly on the
 143         generic route base class</dd></dl>
 144      */
 145     template <class Source, class Target>
 146     class Route
 147         : public detail::RouteImplementation<Source,Target>
 148     {
 149     private:
 150         typedef detail::RouteImplementation<Source,Target> Base;
 151         typedef detail::RouteImplementation<Source,Target> Implementation;
 152
 153         Route(module::Module & module, Source & source, Target & target);
 154
 155         friend class module::Module;
 156     };
 157
 158 }}
 159
 160 ///////////////////////////////hh.e////////////////////////////////////////
 161 #include "Route.cci"
 162 #include "Route.ct"
 163 #include "Route.cti"
 164 #endif
 165
 166 \f
 167 // Local Variables:
 168 // mode: c++
 169 // fill-column: 100
 170 // c-file-style: "senf"
 171 // indent-tabs-mode: nil
 172 // ispell-local-dictionary: "american"
 173 // compile-command: "scons -u test"
 174 // comment-column: 40
 175 // End: