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 namespace module {
  38
  39     /** \brief Module baseclass
  40
  41         senf::ppi::Module is the baseclass of all PPI modules. It provides the module implementation
  42         with interfaces to several PPI facilities:
  43
  44         \li Connector management
  45         \li Flow management (routing)
  46         \li Event handling
  47
  48         To provide internal bookkeeping, most access to the PPI infrastructure is managed through
  49         this base class.
  50
  51         Instances of this class may be allocated either statically or dynamically. Dynamic instances
  52         are automatically managed using the dynamicModule adaptor.
  53      */
  54     class Module
  55         : boost::noncopyable
  56     {
  57     protected:
  58         Module();
  59         ~Module();
  60
  61         template <class Source, class Target>
  62         Route<Source, Target> & route(Source const & source, Target const & target);
  63                                         ///< Define flow information
  64                                         /**< Using the route() and noroute() members, the
  65                                              information flow within the module is defined. Routing
  66                                              may be specified either between inputs, outputs and
  67                                              events. The routing information is used to perform
  68                                              automatic throttling. The throttling behavior may
  69                                              however be controlled manually.
  70
  71                                              Even if no automatic throttling is desired <em>it is
  72                                              vital to define the flow information for all inputs and
  73                                              outputs</em>. Without flow information important
  74                                              internal state of the module cannot be
  75                                              initialized. This includes, explicitly defining
  76                                              terminal inputs and outputs using noroute. Event
  77                                              routing however is optional.
  78
  79                                              The return value may be used to alter routing
  80                                              parameters like throttling parameters.
  81
  82                                              \param[in] source Data source, object which controls
  83                                                  incoming data
  84                                              \param[in] target Data target, object which controls
  85                                                  outgoing data
  86                                              \returns Route instance describing this route */
  87
  88         template <class Connector>
  89         void noroute(Connector const & connector); ///< Define terminal connectors
  90                                         /**< The noroute() member explicitly declares, that a
  91                                              connector is terminal and does not directly
  92                                              receive/forward data from/to some other
  93                                              connector. <em>It is mandatory to define routing
  94                                              information for terminal connectors</em>.
  95
  96                                              See the route() documentation for more on routing
  97
  98                                              \param[in] connector Terminal connector to declare */
  99
 100         template <class Target, class Descriptor>
 101         void registerEvent(Target target, Descriptor const & descriptor);
 102                                         ///< Register an external event
 103                                         /**< The \a target argument may be either an arbitrary
 104                                              callable object or it may be a member function pointer
 105                                              pointing to a member function of the Module derived
 106                                              classed. The handler may \e optionally take an Argument
 107                                              of type <tt>typename Descriptor::Event const
 108                                              &</tt>. This object allows to access detailed
 109                                              information on the event delivered.
 110
 111                                              The \a descriptor describes the event to signal. This
 112                                              may be a timer event or some type of I/O event on a
 113                                              file descriptor or socket.
 114
 115                                              \param[in] target The handler to call whenever the
 116                                                  event is signaled
 117                                              \param[in] descriptor The type of event to register */
 118
 119         boost::posix_time::ptime eventTime(); ///< Return timestamp of the currently processing
 120                                               ///< event
 121     };
 122
 123     /** \brief Connect compatible connectors
 124
 125         connect() will connect two compatible connectors: One connector must be active, the other
 126         passive.
 127      */
 128     template <class Source, class Target>
 129     void connect(Source const & source, Target const & target);
 130
 131 }}}
 132
 133 ///////////////////////////////hh.e////////////////////////////////////////
 134 //#include "Module.cci"
 135 //#include "Module.ct"
 136 //#include "Module.cti"
 137 #endif
 138
 139 \f
 140 // Local Variables:
 141 // mode: c++
 142 // fill-column: 100
 143 // c-file-style: "senf"
 144 // indent-tabs-mode: nil
 145 // ispell-local-dictionary: "american"
 146 // compile-command: "scons -u test"
 147 // End: