4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief Module public header
27 #ifndef HH_SENF_PPI_Module_
28 #define HH_SENF_PPI_Module_ 1
32 #include <boost/utility.hpp>
33 #include <boost/ptr_container/ptr_vector.hpp>
34 #include "../Scheduler/ClockService.hh"
36 #include "ModuleManager.hh"
38 //#include "Module.mpp"
39 ///////////////////////////////hh.p////////////////////////////////////////
45 /** \namespace senf::ppi::module
48 The modules build the PPI core. The PPI provides a set of general purpose infrastructure
49 modules. For concrete applications, additional application specific processing modules need
52 \section module_impl Implementing Modules
54 All modules derive from senf::ppi::module::Module. See this class for a documentation on how
57 \section infrastructure_modules General Purpose Modules
59 The PPI provided general purpose modules can be grouped into several categories
61 \li \ref io_modules receive external data or forward packets out of the PPI
62 \li \ref routing_modules forward packets within the network
63 \li \ref adapter_modules are used to connect incompatible connectors to each other
65 \todo Implement Spliters: PassiveSplitter, PrioritySplitter, CloneSplitter
68 /** \defgroup io_modules Source/Sink Modules
70 Source and Sink modules generate or absorb packets in some way: Reading data from a file
71 descriptor, discarding packets etc.
74 /** \defgroup routing_modules Routing Modules
76 Routing modules perform packet forwarding within the network. They do not process the packet
77 data, they just route it.
80 /** \defgroup adapter_modules Adapter Modules
82 Adapter modules adapt incompatible connectors to each other. They allow connection a pair of
83 active or passive connectors.
86 /** \brief Module base-class
88 senf::ppi::Module is the base-class of all PPI modules. It provides the module implementation
89 with interfaces to several PPI facilities:
91 \li Connector management
92 \li Flow management (routing)
95 To provide internal bookkeeping, most access to the PPI infrastructure is managed through
96 this base class. This is an example module specification:
98 class SomeModule : public senf::ppi::module::Module
100 SENF_PPI_MODULE(SomeModule);
102 senf::FileHandle handle;
104 // If needed, define events
105 senf::ppi::IOEvent event;
108 // Define connectors. Any number and type of connectors may be defined. Connectors
109 // must be public since they need to be accessed to connect modules with each other.
110 senf::ppi::connector::PassiveInput<> input;
111 senf::ppi::connector::ActiveOutput<> output;
113 SomeModule(senf::FileHandle h)
115 event ( handle, senf::ppi::IOEvent::Read )
117 // Set up routing. If some connector is not routed you need to explicitly state this
119 route( input, output );
120 route( event, output )
121 .autoThrottling( false );
123 // Register event handlers
124 registerEvent( event, &SomeModule::read );
126 // Register passive connector handlers
127 input.onRequest( &SomeModule::outputRequest );
129 // If needed, you may register throttling event handlers
130 output.onThrottle( &SomeModule::throttle );
131 output.onUnthrottle( &SomeModule::unthrottle );
135 // Called whenever the 'handle' is readable. Read data, do processing and so
136 // on. This example reads the data, puts it into an ethernet packet and sends the
137 // packet out via the active output.
138 output(senf::EthernetPacket::create(handle.read()))
141 void outputRequest() {
142 // Called whenever a packet is sent into the input to. Here we just forward it to
143 // the output if it is an EthernetPacket
144 senf::EthernetPacket p (input().find<EthernetPacket>(senf::nothrow));
150 // Called whenever a throttle notification comes in. Here, we just disable the
151 // event (which is stupid since we should just not have disabled autoThrottling on
152 // the route but this is only an example which tries to be simple ...)
156 void onUnthrottle() {
157 // and for unthrottle notifications
162 // Optional. Called after before running the module but after connections have been
163 // set up. This is either directly before senf::ppi::run() or senf::ppi::init() is
164 // called or, for modules created while the PPI is already running, after returning
165 // from all event handlers but before going back to the event loop.
171 If your module only has a single input connector, you should call this connector \c
172 input. If it has only a single output connector, you should call it \c output. This allows
173 to setup connections without stating the connector explicitly (see senf::ppi::connect()).
175 \see \ref ppi_modules
178 : ModuleManager::Initializable, boost::noncopyable
187 template <class Source, class Target>
188 Route<Source, Target> & route(Source & source, Target & target);
190 Route<connector::InputConnector, connector::OutputConnector> &
191 route(connector::InputConnector & input, connector::OutputConnector & output);
192 ///< Define flow information
193 /**< Using the route() and noroute() members, the
194 information flow within the module is defined. Routing
195 may be defined between inputs, outputs and events. The
196 routing information is used to perform automatic
197 throttling. The throttling behavior may however be
200 Even if no automatic throttling is desired <em>it is
201 essential to define the flow information for all inputs
202 and outputs</em>. Without flow information important
203 internal state of the module cannot be
204 initialized. This includes, explicitly defining
205 terminal inputs and outputs using noroute. Event
206 routing is optional however.
208 The return value may be used to alter routing
209 parameters like throttling parameters.
211 \param[in] input Data source, object which controls
212 incoming data (connector or event)
213 \param[in] output Data target, object which controls
214 outgoing data (connector or event)
215 \returns Route instance describing this route
216 \see \ref ppi_throttling
217 \note The real implementation is not provided by three
218 overloads but by a single template member */
220 Route<connector::InputConnector, EventDescriptor> &
221 route(connector::InputConnector & input, EventDescriptor & output);
222 ///< Define flow information
223 /**< Route from a connector to an event. Routing from a
224 connector to an event defines the event as the
225 conceptual 'receiver' of the data. This means, the
226 event is controlling the processing of received data
227 packets (Example: Routing from an input to an IOEvent
228 defines, that input data will be processed whenever the
231 This event routing allows to automatically
232 enable/disable the event on throttling notifications.
236 Route<EventDescriptor, connector::OutputConnector> &
237 route(EventDescriptor & input, connector::OutputConnector & output);
238 ///< Define flow information
239 /**< Route from an event to a connector. Routing from an
240 event to a connector defines the event as the
241 conceptual 'source' of the data. This means, the event
242 controls how packets are sent (Example: Routing from an
243 IOEvent to an output defines, that output data will be
244 generated whenever the event is signaled).
246 This event routing allows to automatically
247 enable/disable the event on throttling notifications.
252 void noroute(connector::Connector & connector); ///< Define terminal connectors
253 /**< The noroute() member explicitly declares, that a
254 connector is terminal and does not directly
255 receive/forward data from/to some other
256 connector. <em>It is mandatory to define routing
257 information for terminal connectors</em>.
259 See the route() documentation for more on routing
261 \param[in] connector Terminal connector to declare */
264 template <class Descriptor, class Target>
265 void registerEvent(Descriptor & descriptor, Target target);
267 template <class Target>
268 void registerEvent(EventDescriptor & descriptor, Target target);
269 ///< Register an external event
270 /**< The \a target argument may be either an arbitrary
271 callable object or it may be a member function pointer
272 pointing to a member function of the Module derived
273 classed. The handler may \e optionally take an Argument
274 of type <tt>Descriptor::Event const &</tt>. This object
275 allows to access detailed information on the event
278 The \a descriptor describes the event to signal like a
279 timer event or some type of I/O event on a file
280 descriptor or socket.
282 \param[in] target The handler to call whenever the
284 \param[in] descriptor The type of event to register
285 \note The real implementation has the second arguments
286 type as an additional template parameter. */
289 ClockService::clock_type time() const; ///< Time-stamp of the currently processing event
290 /**< If available, this returns the scheduled time of the
293 ClockService::clock_type now() const; ///< Current time of the currently processing event
296 virtual void macro_SENF_PPI_MODULE_missing() = 0;
300 virtual void v_init(); ///< Called after module setup
301 /**< This member is called directly before the PPI (resumes)
302 execution. It is called after connections have been
303 setup before entering the PPI main loop.
305 You may overload this member. Your overload should
306 always call the base-class implementation. */
314 EventManager & eventManager() const;
315 ModuleManager & moduleManager() const;
317 void registerConnector(connector::Connector & connector);
318 RouteBase & addRoute(std::auto_ptr<RouteBase> route);
320 typedef std::vector<connector::Connector *> ConnectorRegistry;
321 ConnectorRegistry connectorRegistry_;
323 typedef boost::ptr_vector<RouteBase> RouteInfoBase;
324 RouteInfoBase routes_;
326 template <class Source, class Target>
327 friend class detail::RouteHelper;
328 friend class senf::ppi::ModuleManager;
331 /** \brief Define PPI Module
333 Every module must begin by using this macro.
335 \see senf::ppi::module::Module
337 # define SENF_PPI_MODULE(name) \
339 ~ name() { destroy(); } \
340 void macro_SENF_PPI_MODULE_missing() {} \
345 ///////////////////////////////hh.e////////////////////////////////////////
346 #include "Module.cci"
348 //#include "Module.cti"
355 // c-file-style: "senf"
356 // indent-tabs-mode: nil
357 // ispell-local-dictionary: "american"
358 // compile-command: "scons -u test"
359 // comment-column: 40