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 <boost/utility.hpp>
  30 #include <boost/date_time/posix_time/posix_time_types.hpp>
  31
  32 //#include "Module.mpp"
  33 ///////////////////////////////hh.p////////////////////////////////////////
  34
  35 namespace senf {
  36 namespace ppi {
  37
  38     /** \brief Module baseclass
  39
  40         senf::ppi::Module is the baseclass of all PPI modules. It provides the module implementation
  41         with interfaces to several PPI facilities:
  42
  43         \li Connector management
  44         \li Flow management (routing)
  45         \li Event handling
  46
  47         To provide internal bookkeeping, most access to the PPI infrastructure is managed through
  48         this base class.
  49
  50         Instances of this class may be allocated either statically or dynamically. Dynamic instances
  51         are automatically managed using the dynamicModule adaptor.
  52      */
  53     class Module
  54         : boost::noncopyable
  55     {
  56     protected:
  57         Module();
  58         ~Module();
  59
  60         template <class Source, class Target>
  61         Route<Source, Target> & route(Source const & source, Target const & target);
  62                                         ///< Define flow information
  63                                         /**< Using the route() and noroute() members, the
  64                                              information flow within the module is defined. Routing
  65                                              may be specified either between inputs, outputs and
  66                                              events. The routing information is used to perform
  67                                              automatic throttling. The throttling behavior may
  68                                              however be controlled manually.
  69
  70                                              Even if no automatic throttling is desired <em>it is
  71                                              vital to define the flow information for all inputs and
  72                                              outputs</em>. Without flow information important
  73                                              internal state of the module cannot be
  74                                              initialized. This includes, explicitly defining
  75                                              terminal inputs and outputs using noroute. Event
  76                                              routing however is optional.
  77
  78                                              The return value may be used to alter routing
  79                                              parameters like throttling parameters.
  80
  81                                              \param[in] source Data source, object which controlls
  82                                                  incoming data
  83                                              \param[in] target Data target, object which controlls
  84                                                  outgoing data
  85                                              \returns Route instance describing this route */
  86
  87         template <class Connector>
  88         void noroute(Connector const & connector); ///< Define terminal connectors
  89                                         /**< The noroute() member explicitly declares, that a
  90                                              connector is terminal and does not directly
  91                                              receive/forward data from/to some other
  92                                              connector. <em>It is mandatory to define routing
  93                                              information for terminal connectors</em>.
  94
  95                                              See the route() documentation for more on routing
  96
  97                                              \param[in] connector Terminal connector to declare */
  98
  99         template <class Target, class Descriptor>
 100         typename Descriptor & registerEvent(Target target, Descriptor const & descriptor);
 101                                         ///< Register an external event
 102                                         /**< The \a target argument may be either an arbitrary
 103                                              callable object or it may be a member function pointer
 104                                              pointing to a member function of the Module derived
 105                                              classed. The handler may \e optionally take an Argument
 106                                              of type <tt>typename Descriptor::Event const
 107                                              &</tt>. This object allows to access detailed
 108                                              information on the event delivered.
 109
 110                                              The \a descriptor describes the event to signal. This
 111                                              may be a timer event or some type of I/O event on a
 112                                              file descriptor or socket.
 113
 114                                              The return value may be used to modify the
 115                                              binding. This allows to temporarily inhibit event
 116                                              delivery or to remove the binding explicitly. Depending
 117                                              on the type of event, other operations may be
 118                                              possible. See the event descriptor documentation.
 119
 120                                              \param[in] target The handler to call whenever the event
 121                                                  is signaled
 122                                              \param[in] descriptor The type of event to register
 123                                              \returns An event binding instance of the appropriate
 124                                                  type. */
 125
 126         boost::posix_time::ptime eventTime(); ///< Return timestamp of the currently processing event
 127     };
 128
 129     /** \brief Automatically manage dynamic module deallocation
 130
 131         The dynamicModule helper will create a new dynamically managed module instance.
 132
 133         The \a args template parameter is only a placeholder. All arguments to dynamicModule will be
 134         passed to the Module constructor.
 135
 136         \implementation dynamicModule should just register the Instance in a different way with the
 137             Infrastructure and return a reference to the new module.
 138      */
 139     template <class Module, class Args>
 140     unspecified dynamicModule(Args args);
 141
 142
 143     /** \brief Connect compatible connectors
 144
 145         connect() will connect two compatible connectors: One connector must be active, the other
 146         passive.
 147      */
 148     template <class Source, class Target>
 149     void connect(Source const & source, Target const & target);
 150
 151     /** \brief Connect connectors via an adaptor module
 152
 153         This connect() overload will insert an additional adaptor module into the connection. The
 154         Adaptor module must have two connectors, \a input and \a output. The call will setup the
 155         connections \a source to \a input and \a output to \a target. Each connector pair must be
 156         compatible.
 157      */
 158     template <class Source, class Target, class Adaptor)
 159     Adaptor const &  connect(Source const & source, Target const & target,
 160                              Adaptor const & adaptor);
 161
 162 }}
 163
 164 ///////////////////////////////hh.e////////////////////////////////////////
 165 //#include "Module.cci"
 166 //#include "Module.ct"
 167 //#include "Module.cti"
 168 #endif
 169
 170 \f
 171 // Local Variables:
 172 // mode: c++
 173 // fill-column: 100
 174 // c-file-style: "senf"
 175 // indent-tabs-mode: nil
 176 // ispell-local-dictionary: "american"
 177 // End: