X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Examples%2FRateStuffer%2FMainpage.dox;h=6d034ebb56300a5f4c0186e85d9ff606f78aacc8;hb=63150647e2d71ad619a15d9d82a2b524658d755d;hp=65fe3ccb0db4bb0c3d175ff94001dcda6aed4533;hpb=e8b91aa6a817af6d9a3714e7b66be6c0d6b0a4e5;p=senf.git diff --git a/Examples/RateStuffer/Mainpage.dox b/Examples/RateStuffer/Mainpage.dox index 65fe3cc..6d034eb 100644 --- a/Examples/RateStuffer/Mainpage.dox +++ b/Examples/RateStuffer/Mainpage.dox @@ -1,31 +1,38 @@ // $Id$ // -// Copyright (C) 2007 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) -// Stefan Bund +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) // -// This program is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2 of the License, or -// (at your option) any later version. +// The contents of this file are subject to the Fraunhofer FOKUS Public License +// Version 1.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// http://senf.berlios.de/license.html // -// This program is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU General Public License for more details. +// The Fraunhofer FOKUS Public License Version 1.0 is based on, +// but modifies the Mozilla Public License Version 1.1. +// See the full license text for the amendments. // -// You should have received a copy of the GNU General Public License -// along with this program; if not, write to the -// Free Software Foundation, Inc., -// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +// Software distributed under the License is distributed on an "AS IS" basis, +// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License +// for the specific language governing rights and limitations under the License. +// +// The Original Code is Fraunhofer FOKUS code. +// +// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. +// (registered association), Hansastraße 27 c, 80686 Munich, Germany. +// +// Contributor(s): +// Stefan Bund + + +using namespace senf::ppi::module; -/** \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 does not provide enough packets, empty UDP packets will be sent instead. - + \section run Running the example Running the example is a little bit more complicated since we need to provide example UDP @@ -36,7 +43,7 @@ 
     # nc -u -l -p 44345
- + The next command starts the \c ratestuffer 
     # cd .../Examples/RateStuffer
@@ -60,20 +67,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 +97,7 @@
 
     \skip Custom
     \skip #include
-    \until Setup
+    \until PPI
 
     We also define some namespace aliases
 
@@ -103,9 +118,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 +128,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
 
@@ -125,13 +142,13 @@
 
     \skip class
     \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
+
+    First the needed modules are declared. We have
+    - 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
 
@@ -142,9 +159,9 @@
 
     The constructor now initializes all the local objects. We pass the template \a packet to the \a
     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 +170,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,21 +179,19 @@
 
     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.