PPI/Route.hh

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