-// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// $Id$
+//
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
PPI application is built by combining processing modules in a very flexible manner.
\image html scenario.png Target Scenario
-
+
The PPI concept is built around some key concepts
\li The PPI is based on processing \ref ppi_packets. It does not handle stream oriented
\li Data flow throughout the network is governed via flexible automatic or manual \ref
ppi_throttling (throttle notifications).
\li Modules may register additional external \ref ppi_events (file descriptor events or timers).
-
+
The PPI thereby builds on the facilities provided by the other components of the SENF
framework. The target scenario above depicts a diffserv capable UDLR/ULE router including
performance optimizations for TCP traffic (PEP). This router is built by combining several
/** \page ppi_overview PPI Overview and Concepts
- <div class="toc">
- <div>Contents</div>
- <ol>
- <li>\ref ppi_design</li>
- <li>\ref ppi_packets</li>
- <li>\ref ppi_modules</li>
- <li>\ref ppi_connectors</li>
- <li>\ref ppi_connections</li>
- <li>\ref ppi_throttling</li>
- <li>\ref ppi_events</li>
- <li>\ref ppi_run</li>
- <li>\ref ppi_flows</li>
- </ol>
- </div>
+ \autotoc
\section ppi_design Design considerations
The PPI interface is designed to be as simple as possible. It provides sane defaults for all
configurable parameters to simplify getting started. It also automates all resource
management. The throttling infrastructure handles blocking conditions (like input exhaustion)
- automatically.
+ automatically.
\section ppi_packets Packets
The PPI processes packets and uses the <a href="@TOPDIR@/Packets/doc/html/index.html">Packet
- library</a> to handle them. All packets are passed around as generic \ref senf::Packet
- references, the PPI does not enforce any packet type restrictions.
+ library</a> to handle them. All packets are internally passed around as generic \ref
+ senf::Packet references, however connectors may optionally be defined as sending or receiving
+ packets of a specific type only.
\section ppi_modules Modules
- A module is represented by a class derived from senf::ppi::Module. Each module has several
- components:
+ A module is represented by a class derived from senf::ppi::module::Module. Each module has
+ several components:
\li It may have any number of \ref ppi_connectors (inputs and outputs)
\li Each module declares flow information which details the route packets take within the
Of these modules, normally only the application modules need to be implemented since the library
provides an extensive set of reusable modules.
-
- The following example module declares three \ref ppi_connectors "Connectors": \c payload,
+
+ The following example module declares three \ref ppi_connectors "Connectors": \c payload,
\c stuffing and \c output. These connectors are defined as \e public data members so they
can be accessed from the outside. This is important as we will see below.
senf::ppi::IntervalTimer timer_;
public:
- senf::ppi::connector::ActiveInput payload;
- senf::ppi::connector::ActiveInput stuffing;
- senf::ppi::connector::ActiveOutput output;
+ senf::ppi::connector::ActiveInput<> payload;
+ senf::ppi::connector::ActiveInput<> stuffing;
+ senf::ppi::connector::ActiveOutput<> output;
RateStuffer(unsigned packetsPerSecond)
: timer_(1000u, packetsPerSecond)
The module processing is very simple: Whenever a timer tick arrives a packet is sent. If the \c
payload input is ready (see \ref ppi_throttling), a payload packet is sent, otherwise a stuffing
packet is sent. The module will therefore provide a constant stream of packets at a fixed rate
- on \c output (see the
- <a href="@TOPDIR@/Examples/RateStuffer/doc/html/index.html">RateStuffer</a> example application
+ on \c output (see the
+ <a href="@TOPDIR@/Examples/RateStuffer/doc/html/index.html">RateStuffer</a> example application
for a slightly different approach)
-
+
An example module to generate the stuffing packets could be
\code
{
SENF_PPI_MODULE(CopyPacketGenerator);
public:
- senf::ppi::connector::PassiveOutput output;
+ senf::ppi::connector::PassiveOutput<> output;
CopyPacketGenerator(Packet template)
: template_ (template)
\see senf::ppi::module::Module
\section ppi_connectors Connectors
-
+
The input and output attachment points of a module are called connectors. Each connector may be
active or passive. This gives us 4 types of connectors:
To provide this flexibility, all input connectors incorporate a packet queue. This queue is
exposed to the module and allows the module to optionally process packets in batches.
+ Connectors take an optional template argument which allows to specify the type of packet this
+ connector sends or received. This template arguments defaults to \ref senf::Packet.
+
\see \ref senf::ppi::connector
\section ppi_connections Connections
To make use of the modules, they have to be instantiated and connections have to be created
between its connectors. It is possible to connect any pair of input/output connectors as long as
one of them is active and the other is passive.
-
+
It is possible to connect two active or passive connectors with each other using a special
adaptor module (senf::ppi::module::PassiveQueue or senf::ppi::module::ActiveFeeder
respectively).
\code
RateStuffer rateStuffer (10);
- senf::Packet stuffingPacket = senf::DataPacket::create(...);
+ senf::Packet stuffingPacket = senf::DataPacket::create(...);
CopyPacketGenerator generator (stuffingPacket);
senf::UDPv4ClientSocketHandle inputSocket (1111);
- senf::ppi::module::ActiveSocketReader udpInput (inputSocket);
+ senf::ppi::module::ActiveSocketSource<> udpInput (inputSocket);
senf::UDPv4ClientSocketHandle outputSocket ("2.3.4.5:2222");
- senf::ppi::module::PassiveSocketWriter udpOutput (outputSocket);
+ senf::ppi::module::PassiveSocketSink<> udpOutput (outputSocket);
senf::ppi::module::PassiveQueue adaptor;
This application will read udp-packets coming in on port 1111 and will forward
them to port 2222 on host 2.3.4.5 with a fixed rate of 10 packets / second.
-
+
We start out by instantiating the necessary modules. Then the connections between these modules
are set up by successively connecting each output connector to an input connector. As can be
seen, the name of the connector can be left of if it is named \c output or \c input
disabled, see \ref senf::ppi::connector::ActiveConnector) to be called when a throttle
notification is received. The callback may then handle the notification however it sees fit, for
example by manually throttling some passive connector (see \ref
- senf::ppi::connector::PassiveConnector).
+ senf::ppi::connector::PassiveConnector).
- To enable/disable automatic throttling, the \ref senf::ppi::module::Module::route() command
+ To enable/disable automatic throttling, the \ref senf::ppi::module::Module::route() command
returns a reference to a \ref senf::ppi::Route instance. If this route is \e forwarding route,
- (that is, of the connectors is passive and the other is active), the return value will be
+ (that is, of the connectors is passive and the other is active), the return value will be
derived from \ref senf::ppi::ForwardingRoute which provides members to control the throttle
notification forwarding.
-
- \see
+
+ \see
senf::ppi::module::Module \n
senf::ppi::Route
perform the call. This is handled by the <a
href="@TOPDIR@/Scheduler/doc/html/index.html">Scheduler</a>, which is wrapped by the event
classes.
-
+
All events are derived from senf::ppi::EventDescriptor. The base class allows to enable and
disable the event. Each type of event will take descriptor specific constructor arguments to
describe the event to be generated. Events are declared as (private) data members of the
- module and are then registered using senf::ppi::module::Module::registerEvent().
+ module and are then registered using senf::ppi::module::Module::registerEvent().
Each event when signaled is described by an instance of the descriptor specific \e
descriptorType \c ::Event class. This instance will hold the event specific information (like
\section ppi_flows Information Flow
The above description conceptually introduces three different flow levels:
-
+
\li The <em>data flow</em> is, where the packets are flowing. This flow always goes from output
to input connector.
\li The <em>execution flow</em> describes the flow of execution from one module to another. This
Within a module, the different flow levels are defined differently depending on the type of
flow:
-
+
\li The <em>data flow</em> is defined by how data is processed. The different event and
connector callbacks will pass packets around and thereby define the data flow
\li Likewise, the <em>execution flow</em> is defined parallel to the data flow (however possible
*/
/** \page ppi_implementation Implementation Notes
-
+
\section processing Data Processing
The processing in the PPI is driven by events. Without events <em>nothing will happen</em>. When
Every module manages a collection of all it's connectors and every connector has a reference to
it's containing module. In addition, every connector maintains a collection of all it's routing
- targets.
+ targets.
All this data is initialized via the routing statements. This is, why \e every connector must
appear in at least one routing statement: These statements will as a side effect initialize the
instance. This simplifies the PPI usage considerably. The same is true for the connectors: Since
they know the containing module, they can explicitly bind unbound member function pointers to
the instance.
-
+
\section ppi_random_notes Random implementation notes
-
+
Generation of throttle notifications: Backward throttling notifications are automatically
generated (if this is not disabled) whenever the input queue is non-empty \e after the event
handler has finished processing. Forward throttling notifications are not generated
\section ppi_classdiagram Class Diagram
- \image html classes.png
+ <div class="diamap" name="classes">
+ <span coords="652,428,796,455">\ref senf::ppi::connector::PassiveConnector</span>
+ <span coords="198,381,316,408">\ref senf::ppi::EventManager</span>
+ <span coords="462,543,571,570">\ref senf::ppi::connector::ActiveOutput</span>
+ <span coords="468,494,564,521">\ref senf::ppi::connector::ActiveInput</span>
+ <span coords="414,36,505,63">\ref senf::ppi::RouteBase</span>
+ <span coords="432,325,529,379">\ref senf::ppi::Route</span>
+ <span coords="194,154,319,181">\ref (some module)</span>
+ <span coords="19,293,252,333">\ref senf::ppi::EventImplementation</span>
+ <span coords="225,36,289,63">\ref senf::ppi::module::Module</span>
+ <span coords="309,331,397,358">\ref senf::ppi::connector::Connector</span>
+ <span coords="597,543,717,570">\ref senf::ppi::connector::PassiveOutput</span>
+ <span coords="66,432,210,459">\ref senf::ppi::detail::EventBindingBase</span>
+ <span coords="378,428,505,455">\ref senf::ppi::connector::InputConnector</span>
+ <span coords="491,124,694,210">\ref senf::ppi::RouteImplementation</span>
+ <span coords="283,464,423,491">\ref senf::ppi::connector::OutputConnector</span>
+ <span coords="512,428,645,455">\ref senf::ppi::connector::ActiveConnector</span>
+ <span coords="85,487,259,527">\ref senf::ppi::detail::EventBinding</span>
+ <span coords="39,216,170,243">\ref senf::ppi::EventDescriptor</span>
+ <span coords="604,494,710,521">\ref senf::ppi::connector::PassiveInput</span>
+ </div>
+ \htmlonly <img src="classes.png" border="0" alt="classes" usemap="#classes"> \endhtmlonly
*/
-\f
+
// Local Variables:
// mode: c++
// fill-column: 100
projects / senf.git / blobdiff