X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Examples%2FRateStuffer%2FMainpage.dox;h=fb70e0f9a3f7511bf846c7589332da190b032597;hb=ad287a6e1241649e73188edf5b8902e4e65f615d;hp=65fe3ccb0db4bb0c3d175ff94001dcda6aed4533;hpb=e8b91aa6a817af6d9a3714e7b66be6c0d6b0a4e5;p=senf.git diff --git a/Examples/RateStuffer/Mainpage.dox b/Examples/RateStuffer/Mainpage.dox index 65fe3cc..fb70e0f 100644 --- a/Examples/RateStuffer/Mainpage.dox +++ b/Examples/RateStuffer/Mainpage.dox @@ -1,8 +1,8 @@ // $Id$ // -// Copyright (C) 2007 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program is free software; you can redistribute it and/or modify @@ -20,7 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -/** \mainpage RateStuffer: A simple example featuring the Packet Processing Infrastructure +using namespace senf::ppi::module; + +/** \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 @@ -60,20 +62,28 @@ \section setup Module setup - \image html ratestuffer.png + \diaimage ratestuffer.dia 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::ActiveSocketSource reads the incoming UDP packets and sends them into a + 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. The RateFilter \a rateFilter reads packets from it's input at a fixed rate and writes them into - the senf::ppi::module::PassiveSocketWriter \a udpWriter. The senf::ppi::module::PriorityJoin + the senf::ppi::module::PassiveSocketSink \a udpSink. The senf::ppi::module::PriorityJoin 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 @@ -82,7 +92,7 @@ \skip Custom \skip #include - \until Setup + \until PPI We also define some namespace aliases @@ -103,9 +113,9 @@ \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 event is initialized to fire every \a interval nanoseconds. The traffic is routed 'across' + the timer which controls the traffic. This routing lets the module automatically handle + throttling events. The timer is registered to call RateFilter::timeout(). \until } @@ -113,8 +123,10 @@ 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 @@ -127,11 +139,11 @@ \until rateFilter First the needed modules are declared. We have - \li the \a barrier to discard incoming packets sent to fast - \li the \a queue to receive incoming packets and create throttling notifications - \li the \a generator to create the stuffing packets - \li the \a join to combine the input stream from the \a queue with the stuffing packet stream - \li the \a rateFilter to generate the fixed rate output stream + - the \a barrier to discard incoming packets sent to fast + - the \a queue to receive incoming packets and create throttling notifications + - the \a generator to create the stuffing packets + - the \a join to combine the input stream from the \a queue with the stuffing packet stream + - the \a rateFilter to generate the fixed rate output stream \until output @@ -144,7 +156,7 @@ 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 }; @@ -153,7 +165,7 @@ 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 @@ -162,22 +174,20 @@ The \a inputSocket is listening on port 44344 while the \a outputSocket will send packets to port 44345 on localhost. The \a outputSocket uses the senf::ConnectedUDPv4SocketProtocol which - is compatible with the senf::ppi::module::PassiveSocketWriter module. + is compatible with the senf::ppi::module::PassiveSocketSink module. - \until udpWriter + \until udpSink Here we allocate the components: - \li \a udpReader to read the packets from \a inputSocket - \li \a stuffer for the real work and - \li \a udpWriter to send the packets to \a outputSocket + - \a udpSource to read the packets from \a inputSocket + - \a stuffer for the real work and + - \a udpSink 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 }