2 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
3 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
4 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
21 /** \mainpage libPPI : The Packet Processing Infrastructure
23 The PPI provides an infrastructure to create packet oriented network processing applications. A
24 PPI application is built by combining processing modules in a very flexible manner.
26 \image html scenario.png Target Scenario
28 The PPI concept is built around some key concepts
30 \li The PPI is based on processing \ref ppi_packets. It does not handle stream oriented
32 \li The PPI is built around reusable \ref ppi_modules. Each module is completely independent.
33 \li Each module has an arbitrary number of \ref ppi_connectors, inputs and outputs.
34 \li The modules are connected to each other using flexible \ref ppi_connections.
35 \li Data flow throughout the network is governed via flexible automatic or manual \ref
36 ppi_throttling (throttle notifications).
37 \li Modules may register additional external \ref ppi_events (file descriptor events or timers).
39 The PPI thereby builds on the facilities provided by the other components of the SENF
40 framework. The target scenario above depicts a diffserv capable UDLR/ULE router including
41 performance optimizations for TCP traffic (PEP). This router is built by combining several
44 \see \ref ppi_overview \n
45 <a href="../../../Examples/RateStuffer/doc/html/index.html">PPI Example Application:
47 \ref senf::ppi::module "Modules" \n
48 \ref senf::ppi::connector "Connectors" \n
52 /** \page ppi_overview PPI Overview and Concepts
57 <li>\ref ppi_design</li>
58 <li>\ref ppi_packets</li>
59 <li>\ref ppi_modules</li>
60 <li>\ref ppi_connectors</li>
61 <li>\ref ppi_connections</li>
62 <li>\ref ppi_throttling</li>
63 <li>\ref ppi_events</li>
65 <li>\ref ppi_flows</li>
69 \section ppi_design Design considerations
71 The PPI interface is designed to be as simple as possible. It provides sane defaults for all
72 configurable parameters to simplify getting started. It also automates all resource
73 management. The throttling infrastructure handles blocking conditions (like input exhaustion)
76 \section ppi_packets Packets
78 The PPI processes packets and uses the <a href="@TOPDIR@/Packets/doc/html/index.html">Packet
79 library</a> to handle them. All packets are passed around as generic \ref senf::Packet
80 references, the PPI does not enforce any packet type restrictions.
82 \section ppi_modules Modules
84 A module is represented by a class derived from senf::ppi::Module. Each module has several
87 \li It may have any number of \ref ppi_connectors (inputs and outputs)
88 \li Each module declares flow information which details the route packets take within the
89 module. This information does not define how the information is processed, it only tells,
90 where data arriving on some input will be directed at (\ref
91 senf::ppi::module::Module::route())
92 \li The module might take additional parameters.
93 \li The module might also register additional \ref ppi_events.
95 Generally, modules are divided into several categories:
97 \li \ref io_modules receive external data or forward packets out of the PPI
98 \li \ref routing_modules forward packets within the network
99 \li \ref adapter_modules are used to connect incompatible connectors to each other
100 \li Application modules are modules implemented to perform an applications function
102 Of these modules, normally only the application modules need to be implemented since the library
103 provides an extensive set of reusable modules.
105 The following example module declares three \ref ppi_connectors "Connectors": \c payload,
106 \c stuffing and \c output. These connectors are defined as \e public data members so they
107 can be accessed from the outside. This is important as we will see below.
111 : public senf::ppi::module::Module
113 SENF_PPI_MODULE(RateStuffer);
115 senf::ppi::IntervalTimer timer_;
118 senf::ppi::connector::ActiveInput payload;
119 senf::ppi::connector::ActiveInput stuffing;
120 senf::ppi::connector::ActiveOutput output;
122 RateStuffer(unsigned packetsPerSecond)
123 : timer_(1000u, packetsPerSecond)
125 route(payload, output);
126 route(stuffing, output);
128 registerEvent( timer_, &RateStuffer::tick );
142 The constructor will declare flow information using senf::ppi::module::Module::route(). Then the
143 module registers an interval timer which will fire <tt>packetsPerSecond</tt> times every
144 <tt>1000</tt> milliseconds.
146 The module processing is very simple: Whenever a timer tick arrives a packet is sent. If the \c
147 payload input is ready (see \ref ppi_throttling), a payload packet is sent, otherwise a stuffing
148 packet is sent. The module will therefore provide a constant stream of packets at a fixed rate
149 on \c output (see the
150 <a href="@TOPDIR@/Examples/RateStuffer/doc/html/index.html">RateStuffer</a> example application
151 for a slightly different approach)
153 An example module to generate the stuffing packets could be
156 class CopyPacketGenerator
157 : public senf::ppi::module::Module
159 SENF_PPI_MODULE(CopyPacketGenerator);
161 senf::ppi::connector::PassiveOutput output;
163 CopyPacketGenerator(Packet template)
164 : template_ (template)
167 output.onRequest(&CopyPacketGenerator::makePacket);
175 output(template_.clone());
180 This module just produces a copy of a given packet whenever output is requested.
182 \see senf::ppi::module::Module
184 \section ppi_connectors Connectors
186 The input and output attachment points of a module are called connectors. Each connector may be
187 active or passive. This gives us 4 types of connectors:
189 \li senf::ppi::connector::ActiveInput
190 \li senf::ppi::connector::ActiveOutput
191 \li senf::ppi::connector::PassiveInput
192 \li senf::ppi::connector::PassiveOutput
194 An \e active connector (input or output) is <em>activated by the module</em> to send data or to
195 poll for available packets. This means, the modules processing routine will call the connector
196 without being signaled by the framework to read the connector. It just actively fetches a
199 A \e passive connector is <em>signaled by the framework</em> to fetch data from the module or to
200 pass data into the module. The module must register a callback which will be called, whenever a
201 packet is requested from the module or whenever a new packet is made available for the module to
204 To send or receive a packet (either actively or passively) the module just calls the
205 connector. It is permissible to generate or process multiple packets in one iteration. However,
206 you must ensure yourself that enough packets are available to be read if more than one packet
207 shall be read. It is also permissible to not handle a packet at all even if signaled to do
208 so. The packet will automatically be queued.
210 To provide this flexibility, all input connectors incorporate a packet queue. This queue is
211 exposed to the module and allows the module to optionally process packets in batches.
213 \see \ref senf::ppi::connector
215 \section ppi_connections Connections
217 \image html ratestuffer.png Simple RateStuffer
219 To make use of the modules, they have to be instantiated and connections have to be created
220 between its connectors. It is possible to connect any pair of input/output connectors as long as
221 one of them is active and the other is passive.
223 It is possible to connect two active or passive connectors with each other using a special
224 adaptor module (senf::ppi::module::PassiveQueue or senf::ppi::module::ActiveFeeder
227 To complete our simplified example: Lets connet senf::ppi::module::ActiveSocketReader and
228 senf::ppi::module::PassiveSocketWriter to our example module:
231 RateStuffer rateStuffer (10);
233 senf::Packet stuffingPacket = senf::DataPacket::create(...);
234 CopyPacketGenerator generator (stuffingPacket);
236 senf::UDPv4ClientSocketHandle inputSocket (1111);
237 senf::ppi::module::ActiveSocketReader udpInput (inputSocket);
239 senf::UDPv4ClientSocketHandle outputSocket ("2.3.4.5:2222");
240 senf::ppi::module::PassiveSocketWriter udpOutput (outputSocket);
242 senf::ppi::module::PassiveQueue adaptor;
244 senf::ppi::connect(udpInput, adaptor);
245 senf::ppi::connect(adaptor, rateStuffer.payload);
246 adaptor.qdisc(ThresholdQueueing(10,5));
247 senf::ppi::connect(generator, rateStuffer.stuffing);
248 senf::ppi::connect(rateStuffer, udpOutput);
253 This application will read udp-packets coming in on port 1111 and will forward
254 them to port 2222 on host 2.3.4.5 with a fixed rate of 10 packets / second.
256 We start of by instantiating the necessary modules. Then the connections between these modules
257 are set up by successively connecting each output connector to an in put connector. As can be
258 seen, the name of the connector can be left of if it is named \c output or \c input
261 The buffering on the udpInput <-> rateStuffer adaptor is changed so the queue will begin to
262 throttle only if more than 10 packets are in the queue. The connection will be unthrottled as
263 soon as there are no more than 5 packets left in the queue (see \ref ppi_throttling).
265 \section ppi_throttling Throttling
267 Throttling and throttle notifications at it's base is about handling blocking conditions. The
268 most straight forward blocking condition is that of a file descriptor not being available for
269 reading resp. writing. Other blocking conditions can arise for example when a queue fills up or
270 if a module for some application specific reason does not want to handle packets for a period of
273 All this is handled using throttle notifications. We need throttle notifications so a passive
274 connector can tell it's connected peer that it cannot service further requests until an
275 unthrottle notification is sent. This tells us, that from the view of someone implementing a
276 module, throttle notifications will always be received on active connectors and be sent on
279 This tells us, that the direction of control flow (the throttle notifications) is from passive
280 to active connectors and does \e not depend on the direction of data flow (which flows from
281 output to input connector). Thinking about this, this makes sense: The module with the active
282 connector is the one initiating the data processing (after all, it is the \e active part) and
283 needs to be told not to request or send packets on it's connector since the connected passive
284 peer cannot handle the request.
286 So if a passive connector cannot handle requests, the connector must be \e throttled. Throttling
287 the connector will forward a throttle notification to its peer. The peer then handles the
288 throttling notification.
290 There are two ways, throttle notifications can be handled: By automatic throttling or by
291 registering callbacks. The default is <em>automatic throttling</em>.
293 <em>Automatic throttling</em> is based on the routing information available to the module. Every
294 notification received is forwarded within the module along all known routes from active to
295 passive connectors (routes which connect to active or passive connectors are absolutely valid,
296 they just are not \e forwarding routes, they are ignored by the throttle
297 notifications). Together with automatic event throttling (see \ref ppi_events), this is all that
298 is normally needed to handle throttle notifications: By forwarding the notifications we ensure,
299 that a module's passive connectors will only be signaled when it's corresponding active
300 connectors are not throttled (as defined by the routing information). The module is therefore
301 not called until the connector(s) are untrhottled.
303 <em>Throttle callbacks</em> can optionaly be registerd (with automatic throttling enabled or
304 disabled, see \ref senf::ppi::connector::ActiveConnector) to be called when a throttle
305 notification is received. The callback may then handle the notification however it sees fit, for
306 example by manually throttling some passive connector (see \ref
307 senf::ppi::connector::PassiveConnector).
309 To enable/disable automatic throttling, the \ref senf::ppi::module::Module::route() command
310 returns a reference to a \ref senf::ppi::Route instance. If this route is \e forwarding route,
311 (that is, of the connectors is passive and the other is active), the return value will be
312 derived from \ref senf::ppi::ForwardingRoute which provides members to control the throttle
313 notification forwarding.
316 senf::ppi::module::Module \n
319 \section ppi_events Events
321 Modules may register additional events. These external events are very important since they
322 drive the PPI framework. Events are like external calls into the module network which are sent
323 whenever some event happens. Some possible events are
324 \li timer events (senf::ppi::IntervalTimer)
325 \li read or write events on some file descriptor (senf::ppi::IOEvent)
326 \li internal events (senf::ppi::IdleEvent)
328 The PPI really is not concerned, how the events are called and what information is needed to
329 perform the call. This is handled by the <a
330 href="@TOPDIR@/Scheduler/doc/html/index.html">Scheduler</a>, which is wrapped by the event
333 All events are derived from senf::ppi::EventDescriptor. The base class allows to enable and
334 disable the event. Each type of event will take descriptor specific constructor arguments to
335 describe the event to be generated. Events are declared as (private) data members of the
336 module and are then registered using senf::ppi::module::Module::registerEvent().
338 Each event when signaled is described by an instance of the descriptor specific \e
339 descriptorType \c ::Event class. This instance will hold the event specific information (like
340 scheduled time of the event, file handle state and so on). This information is passed to the
343 Additionaly, events are valid routing targets. This feature allows events to be disabled and
344 enabled by throtling notifications. For the sake of routing, an event may be used like an active
345 input or output. Iit is \e active from the PPI's point of view since it is signaled from the
346 outside and not by some module. It may be either input or output depending on the operation the
349 If we take into account event routing, we can extend the \c RateStuffer constructor accordingly:
352 RateStuffer(unsigned packetsPerSecond)
353 : timer_(1000u, packetsPerSecond)
355 route(payload, output);
356 route(stuffing, output);
357 route(timer_, output); // (*)
359 registerEvent( timer_, &RateStuffer::tick );
363 We have added the marked route call. This way, the \c timer_ will receive throttling
364 notifications from the output: Whenever the output is throttled, the event will be disabled
365 until the output is unthrottled again.
367 \see senf::ppi::EventDescriptor
369 \section ppi_run Running the network
371 After the network has been set up, senf::ppi::run() is called to execute it. This call will only
372 return after all data has been processed. The PPI knows this, when no events are enabled any
373 more. Without events, nothing will happen any more since it is the events which drive the
374 PPI. Therefore the PPI surmises, that all data has been processed and returns from
377 This works very well with automatic throttling. When no data is available to be processed any
378 more and no more data can be expected to arrive (for Example since data has been read from a
379 file which is now exhausted) all events will be disabled automatically via trhottle
380 notifications and so signal that any processing should stop.
382 \section ppi_flows Information Flow
384 The above description conceptually introduces three different flow levels:
386 \li The <em>data flow</em> is, where the packets are flowing. This flow always goes from output
388 \li The <em>execution flow</em> describes the flow of execution from one module to another. This
389 flow always proceeds from active to passive connector.
390 \li The <em>control flow</em> is the flow of throttling notifications. This flow always proceeds
391 \e opposite to the execution flow, from passive to active connector.
393 This is the outside view, from without any module. These flows are set up using
394 senf::ppi::connect() statements.
396 Within a module, the different flow levels are defined differently depending on the type of
399 \li The <em>data flow</em> is defined by how data is processed. The different event and
400 connector callbacks will pass packets around and thereby define the data flow
401 \li Likewise, the <em>execution flow</em> is defined parallel to the data flow (however possible
402 in opposite direction) by how the handler of one connector calls other connectors.
403 \li The <em>control flow</em> is set up using senf::ppi::Module::route statements (as long as
404 automatic throttling is used. Manual throttling defines the control flow within the
405 respective callbacks).
407 In nearly all cases, these flows will be parallel. Therefore it makes sense to define the \c
408 route statement as defining the 'conceptual data flow' since this is also how control messages
409 should flow (sans the direction, which is defined by the connectors active/passive property).
411 \see \ref ppi_implementation
414 /** \page ppi_implementation Implementation Notes
416 \section processing Data Processing
418 The processing in the PPI is driven by events. Without events <em>nothing will happen</em>. When
419 an event is generated, the called module will probably call one of it's active connectors.
421 Calling an active connector will directly call the handler registered at the connected passive
422 connector. This way the call and data are handed across the connections until an I/O module will
423 finally handle the request (by not calling any other connectors).
425 Throttling is handled in the same way: Throttling a passive connector will call a corresponding
426 (internal) method of the connected active connector. This method will call registered handlers
427 and will analyze the routing information of the module for other (passive) connectors to call
428 and throttle. This will again create a call chain which terminates at the I/O modules. An event
429 which is called to be throttled will disable the event temporarily. Unthrottling works in the
432 This simple structure is complicated by the existence of the input queues. This affects both
433 data forwarding and throttling:
434 \li A data request will only be forwarded, if no data is available in the queue
435 \li The connection will only be throttled when the queue is empty
436 \li Handlers of passive input connectors must be called repeatedly until either the queue is
437 empty or the handler does not take any packets from the queue
440 \section ppi_logistics Managing the Data Structures
442 The PPI itself is a singleton. This simplifies many of the interfaces (We do not need to pass
443 the PPI instance). Should it be necessary to have several PPI systems working in parallel
444 (either by registering all events with the same event handler or by utilizing multiple threads),
445 we can still extend the API by adding an optional PPI instance argument.
447 Every module manages a collection of all it's connectors and every connector has a reference to
448 it's containing module. In addition, every connector maintains a collection of all it's routing
451 All this data is initialized via the routing statements. This is, why \e every connector must
452 appear in at least one routing statement: These statements will as a side effect initialize the
453 connector with it's containing module.
455 Since all access to the PPI via the module is via it's base class, unbound member function
456 pointers can be provided as handler arguments: They will automatically be bound to the current
457 instance. This simplifies the PPI usage considerably. The same is true for the connectors: Since
458 they know the containing module, they can explicitly bind unbound member function pointers to
461 \section ppi_random_notes Random implementation notes
463 Generation of throttle notifications: Backward throttling notifications are automatically
464 generated (if this is not disabled) whenever the input queue is non-empty \e after the event
465 handler has finished processing. Forward throttling notifications are not generated
466 automatically within the connector. However, the Passive-Passive adaptor will generate
467 Forward-throttling notifications whenever the input queue is empty.
469 \section ppi_classdiagram Class Diagram
471 \image html classes.png
478 // c-file-style: "senf"
479 // indent-tabs-mode: nil
480 // ispell-local-dictionary: "american"