// $Id$
//
// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// 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
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-/** \mainpage RateStuffer: A simple example featuring the Packet Processing Infrastructure
+/** \mainpage Example introducing the Packet Processing Infrastructure
This example application implements a simple PPI application: It will read UDP packets from an
input port and will forward them to another port at a fixed packet rate. If the input stream
Above image depicts the module setup implementing the rate stuffer. A
senf::ppi::module::ActiveSocketReader reads the incoming UDP packets and sends them into a
- senf::ppi::module::PassiveQueue.
+ senf::ppi::module::PassiveQueue (via a senf::ppi::module::ThrottleBarrier).
The \a queue feeds the packets into a senf::ppi::module::PriorityJoin. The CloneSource
\a generator is fed as second input into the \a join to provide the stuffing packets.
ensures that read requests of the RateStuffer's input are always serviced, either from the \a
queue or, if the \a queue output is throttled, from the \a generator.
+ The \a barrier is not strictly necessary. However, it makes the behavior of the RateStuffer
+ predictable in the case where packets need to be dropped. Without the
+ senf::ppi::module::ThrottleBarrier, the packets will be left in the kernel socket queue. Packets
+ will only start to be dropped when that queue fills up. The size of this queue cannot be easily
+ manipulated and it's initial size is immense. So to stop the kernel queue from filling up with
+ increasingly out-of-date packets, we add the \a barrier which will explicitly read and drop
+ excess packets.
+
\section code Example code
\dontinclude ratestuffer.cc
\skip Custom
\skip #include
- \until Setup
+ \until PPI
We also define some namespace aliases
\until }
The event is initialized to fire eery \a interval nanoseconds. The traffic is routed 'across'
- the timer which controls the traffic. The timer is then registered to call
- RateFilter::timeout().
+ the timer which controls the traffic. This routing lets the module automatically handle
+ throttling events. The timer is registered to call RateFilter::timeout().
\until }
and forwarded to \a output.
This is all there is to the RateFilter module. Due to the routing setup, the timer will
- automatically be disabled if either \a input or \a output become throttled (which is not even
- needed here).
+ automatically be disabled should either \a input or \a output become throttled. However, in this
+ specific case this should never happen: The \a input is connected (via the \a join) to the
+ senf::ppi::module::CloneSource, which will never throttle. The \a output is connected to a UDP
+ socket which also never throttles.
\subsection ratestuffer The RateStuffer subnet
generator and set the timing \a interval of the \a rateFilter.
The \a input and \a output connector references are bound to the corresponding connectors we
- want to expose: \a input to the \a queue's \a input and \a output to the \a rateStuffer's \a
+ want to expose: \a input to the \a barrier's \a input and \a output to the \a rateFilter's \a
output.
\until };
discipline of the \a queue. This Completes the RateStuffer. This subnetwork can now be used like
a module.
- \subsection main Connecting the modules
+ \subsection main Application setup
The applications main() method starts out by initializing the socket handles
port 44345 on localhost. The \a outputSocket uses the senf::ConnectedUDPv4SocketProtocol which
is compatible with the senf::ppi::module::PassiveSocketWriter module.
- \until udpWriter
+ \until udpSink
Here we allocate the components:
\li \a stuffer for the real work and
\li \a udpWriter to send the packets to \a outputSocket
- \until udpWriter
+ \until udpSink
The \ref senf::ppi::connect() calls setup the necessary connections.
- \until run
-
The module setup is complete, \ref senf::ppi::run() is called to enter the event loop.
\until }