senf/PPI/Route.hh

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