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/date_time/posix_time/posix_time_types.hpp>
  32 #include <boost/ptr_container/ptr_vector.hpp>
  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     protected:
  61         Module();
  62
  63         template <class Source, class Target>
  64         Route<Source, Target> & route(Source & source, Target & target);
  65                                         ///< Define flow information
  66                                         /**< Using the route() and noroute() members, the
  67                                              information flow within the module is defined. Routing
  68                                              may be specified either between inputs, outputs and
  69                                              events. The routing information is used to perform
  70                                              automatic throttling. The throttling behavior may
  71                                              however be controlled manually.
  72
  73                                              Even if no automatic throttling is desired <em>it is
  74                                              vital to define the flow information for all inputs and
  75                                              outputs</em>. Without flow information important
  76                                              internal state of the module cannot be
  77                                              initialized. This includes, explicitly defining
  78                                              terminal inputs and outputs using noroute. Event
  79                                              routing however is optional.
  80
  81                                              The return value may be used to alter routing
  82                                              parameters like throttling parameters.
  83
  84                                              \param[in] source Data source, object which controls
  85                                                  incoming data
  86                                              \param[in] target Data target, object which controls
  87                                                  outgoing data
  88                                              \returns Route instance describing this route */
  89
  90         void noroute(connector::Connector & connector); ///< Define terminal connectors
  91                                         /**< The noroute() member explicitly declares, that a
  92                                              connector is terminal and does not directly
  93                                              receive/forward data from/to some other
  94                                              connector. <em>It is mandatory to define routing
  95                                              information for terminal connectors</em>.
  96
  97                                              See the route() documentation for more on routing
  98
  99                                              \param[in] connector Terminal connector to declare */
 100
 101         template <class Target, class Descriptor>
 102         void registerEvent(Target target, Descriptor & descriptor);
 103                                         ///< Register an external event
 104                                         /**< The \a target argument may be either an arbitrary
 105                                              callable object or it may be a member function pointer
 106                                              pointing to a member function of the Module derived
 107                                              classed. The handler may \e optionally take an Argument
 108                                              of type <tt>typename Descriptor::Event const
 109                                              &</tt>. This object allows to access detailed
 110                                              information on the event delivered.
 111
 112                                              The \a descriptor describes the event to signal. This
 113
 114                                              may be a timer event or some type of I/O event on a
 115                                              file descriptor or socket.
 116
 117                                              \param[in] target The handler to call whenever the
 118                                                  event is signaled
 119                                              \param[in] descriptor The type of event to register */
 120
 121         boost::posix_time::ptime eventTime(); ///< Return timestamp of the currently processing
 122                                               ///< event
 123
 124     private:
 125         EventManager & eventManager();
 126
 127         void registerConnector(connector::Connector & connector);
 128         RouteBase & addRoute(std::auto_ptr<RouteBase> route);
 129
 130         typedef std::vector<connector::Connector *> ConnectorRegistry;
 131         ConnectorRegistry connectorRegistry_;
 132
 133         typedef boost::ptr_vector<RouteBase> RouteInfoBase;
 134         RouteInfoBase routes_;
 135
 136         template <class Source, class Target>
 137         friend class detail::RouteHelper;
 138     };
 139
 140     /** \brief Connect compatible connectors
 141
 142         connect() will connect two compatible connectors: One connector must be active, the other
 143         passive.
 144      */
 145     template <class Source, class Target>
 146     void connect(Source const & source, Target const & target);
 147
 148 }}}
 149
 150 ///////////////////////////////hh.e////////////////////////////////////////
 151 #include "Module.cci"
 152 #include "Module.ct"
 153 //#include "Module.cti"
 154 #endif
 155
 156 \f
 157 // Local Variables:
 158 // mode: c++
 159 // fill-column: 100
 160 // c-file-style: "senf"
 161 // indent-tabs-mode: nil
 162 // ispell-local-dictionary: "american"
 163 // compile-command: "scons -u test"
 164 // comment-column: 40
 165 // End: