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     /** \namespace senf::ppi::module
  43         \brief PPI Modules
  44
  45         The modules build the PPI core. The PPI provides a set of general purpose infrastructure
  46         modules. For concrete applications, additional application specific processing modules need
  47         to be implemented.
  48
  49         \section module_impl Implementing Modules
  50
  51         All modules derive from senf::ppi::module::Module. See this class for a documentation on how
  52         to write new modules.
  53
  54         \section infrastructure_modules General Purpose Modules
  55
  56         The PPI provided general purpose modules can be grouped into several categories
  57
  58         \li \ref io_modules receive external data or forward packets out of the PPI
  59         \li \ref sourcesink_modules generate or absorb packets internally
  60         \li \ref routing_modules forward packets within the network
  61         \li \ref adapter_modules are used to connect incompatible connectors to each other
  62
  63         \todo Implement Spliters: PassiveSplitter, PrioritySplitter, CloneSplitter
  64      */
  65
  66     /** \defgroup io_modules Input/Output Modules
  67
  68         Input/Output Modules receive data from external sources or forward data from the PPI to
  69         outside targets.
  70      */
  71
  72     /** \defgroup sourcesink_modules Source/Sink Modules
  73
  74         Source and Sink modules generate or absorb packets internally. In contrast to \ref
  75         io_modules, they do not communicate outside the PPI.
  76      */
  77
  78     /** \defgroup routing_modules Routing Modules
  79
  80         Routing modules perform packet forwarding within the network. They do not process the packet
  81         data, they just route it.
  82      */
  83
  84     /** \defgroup adapter_modules Adapter Modules
  85
  86         Adapter modules adapt incompatible connectors to each other. They allow connection a pair of
  87         active or passive connectors.
  88      */
  89
  90     /** \brief Module base-class
  91
  92         senf::ppi::Module is the base-class of all PPI modules. It provides the module implementation
  93         with interfaces to several PPI facilities:
  94
  95         \li Connector management
  96         \li Flow management (routing)
  97         \li Event handling
  98
  99         To provide internal bookkeeping, most access to the PPI infrastructure is managed through
 100         this base class. This is an example module specification:
 101         \code
 102         class SomeModule : public senf::ppi::module::Module
 103         {
 104             SENF_PPI_MODULE(SomeModule);
 105
 106             senf::FileHandle handle;
 107
 108             // If needed, define events
 109             senf::ppi::IOEvent event;
 110
 111         public:
 112             // Define connectors. Any number and type of connectors may be defined. Connectors
 113             // must be public since they need to be accessed to connect modules with each other.
 114             senf::ppi::connector::PassiveInput input;
 115             senf::ppi::connector::ActiveOutput output;
 116
 117             SomeModule(senf::FileHandle h)
 118               : handle ( h ),
 119                 event  ( handle, senf::ppi::IOEvent::Read )
 120             {
 121                 // Set up routing. If some connector is not routed you need to explicitly state this
 122                 // using noroute()
 123                 route( input, output );
 124                 route( event, output )
 125                     .autoThrottling( false );
 126
 127                 // Register event handlers
 128                 registerEvent( &SomeModule::read, event );
 129
 130                 // Register passive connector handlers
 131                 input.onRequest( &SomeModule::outputRequest );
 132
 133                 // If needed, you may register throttling event handlers
 134                 output.onThrottle( &SomeModule::throttle );
 135                 output.onUnthrottle( &SomeModule::unthrottle );
 136             }
 137
 138             void read() {
 139                 // Called whenever the 'handle' is readable. Read data, do processing and so
 140                 // on. This example reads the data, puts it into an ethernet packet and sends the
 141                 // packet out via the active output.
 142                 output(senf::EthernetPacket::create(handle.read()))
 143             }
 144
 145             void outputRequest() {
 146                 // Called whenever a packet is sent into the input to. Here we just forward it to
 147                 // the output if it is an EthernetPacket
 148                 senf::EthernetPacket p (input().find<EthernetPacket>(senf::nothrow));
 149                 if (p)
 150                     output(p);
 151             }
 152
 153             void onThrottle() {
 154                 // Called whenever a throttle notification comes in. Here, we just disable the
 155                 // event (which is stupid since we should just not have disabled autoThrottling on
 156                 // the route but this is only an example which tries to be simple ...)
 157                 event.disable();
 158             }
 159
 160             void onUnthrottle() {
 161                 // and for unthrottle notifications
 162                 event.enable();
 163             }
 164
 165         };
 166         \endcode
 167
 168         If your module only has a single input connector, you should call this connector \c
 169         input. If it has only a single output connector, you should call it \c output. This allows
 170         to setup connections without stating the connector explicitly (see senf::ppi::connect()).
 171      */
 172     class Module
 173         : boost::noncopyable
 174     {
 175     public:
 176         virtual ~Module();
 177
 178     protected:
 179         Module();
 180
 181 #ifndef DOXYGEN
 182         template <class Source, class Target>
 183         Route<Source, Target> & route(Source & source, Target & target);
 184 #else
 185         Route<connector::InputConnector, connector::OutputConnector> &
 186         route(connector::InputConnector & input, connector::OutputConnector & output);
 187                                         ///< Define flow information
 188                                         /**< Using the route() and noroute() members, the
 189                                              information flow within the module is defined. Routing
 190                                              may be specified either between inputs, outputs and
 191                                              events. The routing information is used to perform
 192                                              automatic throttling. The throttling behavior may
 193                                              however be controlled manually.
 194
 195                                              Even if no automatic throttling is desired <em>it is
 196                                              vital to define the flow information for all inputs and
 197                                              outputs</em>. Without flow information important
 198                                              internal state of the module cannot be
 199                                              initialized. This includes, explicitly defining
 200                                              terminal inputs and outputs using noroute. Event
 201                                              routing however is optional.
 202
 203                                              The return value may be used to alter routing
 204                                              parameters like throttling parameters.
 205
 206                                              \param[in] source Data source, object which controls
 207                                                  incoming data (connector or event)
 208                                              \param[in] target Data target, object which controls
 209                                                  outgoing data (connector or event)
 210                                              \returns Route instance describing this route */
 211
 212         Route<connector::InputConnector, EventDescriptor> &
 213         route(connector::InputConnector & input, EventDescriptor & output);
 214                                         ///< Define flow information
 215                                         /**< \see \ref route() */
 216
 217         Route<EventDescriptor, connector::OutputConnector> &
 218         route(EventDescriptor & input, connector::OutputConnector & output);
 219                                         ///< Define flow information
 220                                         /**< \see \ref route() */
 221 #endif
 222
 223         void noroute(connector::Connector & connector); ///< Define terminal connectors
 224                                         /**< The noroute() member explicitly declares, that a
 225                                              connector is terminal and does not directly
 226                                              receive/forward data from/to some other
 227                                              connector. <em>It is mandatory to define routing
 228                                              information for terminal connectors</em>.
 229
 230                                              See the route() documentation for more on routing
 231
 232                                              \param[in] connector Terminal connector to declare */
 233
 234         template <class Target, class Descriptor>
 235         void registerEvent(Target target, Descriptor & descriptor);
 236                                         ///< Register an external event
 237                                         /**< The \a target argument may be either an arbitrary
 238                                              callable object or it may be a member function pointer
 239                                              pointing to a member function of the Module derived
 240                                              classed. The handler may \e optionally take an Argument
 241                                              of type <tt>Descriptor::Event const &</tt>. This object
 242                                              allows to access detailed information on the event
 243                                              delivered.
 244
 245                                              The \a descriptor describes the event to signal. This
 246
 247                                              may be a timer event or some type of I/O event on a
 248                                              file descriptor or socket.
 249
 250                                              \param[in] target The handler to call whenever the
 251                                                  event is signaled
 252                                              \param[in] descriptor The type of event to register */
 253
 254         ClockService::clock_type time() const; ///< Time-stamp of the currently processing event
 255                                         /**< If available, this returns the scheduled time of the
 256                                              event. */
 257
 258         ClockService::clock_type now() const; ///< Current time of the currently processing event
 259
 260 #ifndef DOXYGEN
 261         virtual void macro_SENF_PPI_MODULE_missing() = 0;
 262
 263     private:
 264 #endif
 265         virtual void init();            ///< Called just before the network is run
 266
 267 #ifndef DOXYGEN
 268     public:
 269 #endif
 270         void destroy();
 271
 272     private:
 273         EventManager & eventManager() const;
 274         ModuleManager & moduleManager() const;
 275
 276         void registerConnector(connector::Connector & connector);
 277         RouteBase & addRoute(std::auto_ptr<RouteBase> route);
 278
 279         typedef std::vector<connector::Connector *> ConnectorRegistry;
 280         ConnectorRegistry connectorRegistry_;
 281
 282         typedef boost::ptr_vector<RouteBase> RouteInfoBase;
 283         RouteInfoBase routes_;
 284
 285         template <class Source, class Target>
 286         friend class detail::RouteHelper;
 287         friend class senf::ppi::ModuleManager;
 288     };
 289
 290     /** \brief Define PPI Module
 291
 292         Every module must begin by using this macro.
 293
 294         \see senf::ppi::module::Module
 295      */
 296 #   define SENF_PPI_MODULE(name)                                                                  \
 297     public:                                                                                       \
 298         ~ name() { destroy(); }                                                                   \
 299         void macro_SENF_PPI_MODULE_missing() {}                                                   \
 300     private:
 301
 302 }}}
 303
 304 ///////////////////////////////hh.e////////////////////////////////////////
 305 #include "Module.cci"
 306 #include "Module.ct"
 307 //#include "Module.cti"
 308 #endif
 309
 310 \f
 311 // Local Variables:
 312 // mode: c++
 313 // fill-column: 100
 314 // c-file-style: "senf"
 315 // indent-tabs-mode: nil
 316 // ispell-local-dictionary: "american"
 317 // compile-command: "scons -u test"
 318 // comment-column: 40
 319 // End: