PPI/Module.hh

   1 // Copyright (C) 2007
   2 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   3 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   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 Module public header
  23 */
  24
  25 #ifndef HH_Module_
  26 #define HH_Module_ 1
  27
  28 // Custom includes
  29 #include <vector>
  30 #include <boost/utility.hpp>
  31 #include <boost/ptr_container/ptr_vector.hpp>
  32 #include "Scheduler/ClockService.hh"
  33 #include "predecl.hh"
  34
  35 //#include "Module.mpp"
  36 ///////////////////////////////hh.p////////////////////////////////////////
  37
  38 namespace senf {
  39 namespace ppi {
  40 namespace module {
  41
  42     /** \brief Module baseclass
  43
  44         senf::ppi::Module is the baseclass of all PPI modules. It provides the module implementation
  45         with interfaces to several PPI facilities:
  46
  47         \li Connector management
  48         \li Flow management (routing)
  49         \li Event handling
  50
  51         To provide internal bookkeeping, most access to the PPI infrastructure is managed through
  52         this base class.
  53
  54         Instances of this class may be allocated either statically or dynamically. Dynamic instances
  55         are automatically managed using the dynamicModule adaptor.
  56      */
  57     class Module
  58         : boost::noncopyable
  59     {
  60     public:
  61         virtual ~Module();
  62
  63     protected:
  64         Module();
  65
  66         template <class Source, class Target>
  67         Route<Source, Target> & route(Source & source, Target & target);
  68                                         ///< Define flow information
  69                                         /**< Using the route() and noroute() members, the
  70                                              information flow within the module is defined. Routing
  71                                              may be specified either between inputs, outputs and
  72                                              events. The routing information is used to perform
  73                                              automatic throttling. The throttling behavior may
  74                                              however be controlled manually.
  75
  76                                              Even if no automatic throttling is desired <em>it is
  77                                              vital to define the flow information for all inputs and
  78                                              outputs</em>. Without flow information important
  79                                              internal state of the module cannot be
  80                                              initialized. This includes, explicitly defining
  81                                              terminal inputs and outputs using noroute. Event
  82                                              routing however is optional.
  83
  84                                              The return value may be used to alter routing
  85                                              parameters like throttling parameters.
  86
  87                                              \param[in] source Data source, object which controls
  88                                                  incoming data
  89                                              \param[in] target Data target, object which controls
  90                                                  outgoing data
  91                                              \returns Route instance describing this route */
  92
  93         void noroute(connector::Connector & connector); ///< Define terminal connectors
  94                                         /**< The noroute() member explicitly declares, that a
  95                                              connector is terminal and does not directly
  96                                              receive/forward data from/to some other
  97                                              connector. <em>It is mandatory to define routing
  98                                              information for terminal connectors</em>.
  99
 100                                              See the route() documentation for more on routing
 101
 102                                              \param[in] connector Terminal connector to declare */
 103
 104         template <class Target, class Descriptor>
 105         void registerEvent(Target target, Descriptor & descriptor);
 106                                         ///< Register an external event
 107                                         /**< The \a target argument may be either an arbitrary
 108                                              callable object or it may be a member function pointer
 109                                              pointing to a member function of the Module derived
 110                                              classed. The handler may \e optionally take an Argument
 111                                              of type <tt>typename Descriptor::Event const
 112                                              &</tt>. This object allows to access detailed
 113                                              information on the event delivered.
 114
 115                                              The \a descriptor describes the event to signal. This
 116
 117                                              may be a timer event or some type of I/O event on a
 118                                              file descriptor or socket.
 119
 120                                              \param[in] target The handler to call whenever the
 121                                                  event is signaled
 122                                              \param[in] descriptor The type of event to register */
 123
 124         ClockService::clock_type time() const; ///< Return timestamp of the currently processing
 125                                         ///< event
 126
 127         ClockService::clock_type now() const;
 128
 129         void destroy();
 130
 131 #ifndef DOXYGEN
 132         virtual void macro_SENF_PPI_MODULE_missing() = 0;
 133 #endif
 134
 135     private:
 136         virtual void init();
 137
 138         EventManager & eventManager() const;
 139         ModuleManager & moduleManager() const;
 140
 141         void registerConnector(connector::Connector & connector);
 142         RouteBase & addRoute(std::auto_ptr<RouteBase> route);
 143
 144         typedef std::vector<connector::Connector *> ConnectorRegistry;
 145         ConnectorRegistry connectorRegistry_;
 146
 147         typedef boost::ptr_vector<RouteBase> RouteInfoBase;
 148         RouteInfoBase routes_;
 149
 150         template <class Source, class Target>
 151         friend class detail::RouteHelper;
 152         friend class senf::ppi::ModuleManager;
 153     };
 154
 155 #   define SENF_PPI_MODULE(name)                                                                  \
 156     public:                                                                                       \
 157         ~ name() { destroy(); }                                                                   \
 158         void macro_SENF_PPI_MODULE_missing() {}                                                   \
 159     private:
 160
 161 }}}
 162
 163 ///////////////////////////////hh.e////////////////////////////////////////
 164 #include "Module.cci"
 165 #include "Module.ct"
 166 //#include "Module.cti"
 167 #endif
 168
 169 \f
 170 // Local Variables:
 171 // mode: c++
 172 // fill-column: 100
 173 // c-file-style: "senf"
 174 // indent-tabs-mode: nil
 175 // ispell-local-dictionary: "american"
 176 // compile-command: "scons -u test"
 177 // comment-column: 40
 178 // End: