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 #ifndef HH_Module_
  25 #define HH_Module_ 1
  26
  27 // Custom includes
  28 #include <boost/utility.hpp>
  29
  30 //#include "Module.mpp"
  31 ///////////////////////////////hh.p////////////////////////////////////////
  32
  33 namespace senf {
  34 namespace ppi {
  35
  36     /** \brief Module baseclass
  37
  38         senf::ppi::Module is the baseclass of all PPI modules. It provides the module implementation
  39         with interfaces to several PPI facilities:
  40
  41         \li Connector management
  42         \li Flow management
  43         \li Event handling
  44
  45         To provide internal bookkeeping, most access to the PPI infrastructure is managed through
  46         this base class.
  47
  48         Instances of this class may be allocated either statically or dynamically. Dynamic instances
  49         are automatically managed using the dynamicModule adaptor.
  50      */
  51     class Module
  52         : boost::noncopyable
  53     {
  54     protected:
  55         Module();
  56         ~Module();
  57
  58         template <class Source, class Target>
  59         Route route(Source const & source, Target const & target); ///< Define flow information
  60                                         /**< Using the route() and noroute() members, the
  61                                              information flow within the module is defined. Routing
  62                                              may be specified either between inputs, outputs and
  63                                              events. The routing information is used to perform
  64                                              automatic throttling. The throttling behavior may
  65                                              however be controlled manually.
  66
  67                                              Even if no automatic throttling is desired <em>it is
  68                                              vital to define the flow information for all inputs and
  69                                              outputs</em>. Without flow information important
  70                                              internal state of the module cannot be
  71                                              initialized. This includes, explicitly defining
  72                                              terminal inputs and outputs using noroute. Event
  73                                              routing however is optional.
  74
  75                                              The return value may be used to alter routing
  76                                              parameters like throttling parameters.
  77
  78                                              \param[in] source Data source, object which controlls
  79                                                  incoming data
  80                                              \param[in] target Data target, object which controlls
  81                                                  outgoing data
  82                                              \returns Route instance describing this route */
  83
  84         template <class Connector>
  85         void noroute(Connector const & connector); ///<Define terminal connectors
  86                                         /**<
  87
  88                                             The noroute() member explicitly declares, that a
  89                                             connector is terminal and does not directly
  90                                             receive/forward data from/to some other
  91                                             connector. <em>It is mandatory to define routing
  92                                             information for terminal connectors</em>.
  93
  94                                             See the route() documentation for more on routing
  95
  96                                             \param[in] connector Terminal connector to declare */
  97
  98         template <class Target, class Descriptor>
  99         typename Descriptor::EventBinding const registerEvent(Target target,
 100                                                               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
 127 }}
 128
 129 ///////////////////////////////hh.e////////////////////////////////////////
 130 //#include "Module.cci"
 131 //#include "Module.ct"
 132 //#include "Module.cti"
 133 #endif
 134
 135 \f
 136 // Local Variables:
 137 // mode: c++
 138 // fill-column: 100
 139 // c-file-style: "senf"
 140 // indent-tabs-mode: nil
 141 // ispell-local-dictionary: "american"
 142 // End: