Examples/RateStuffer/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \mainpage RateStuffer: A simple example featuring the Packet Processing Infrastructure
  24
  25     This example application implements a simple PPI application: It will read UDP packets from an
  26     input port and will forward them to another port at a fixed packet rate. If the input stream
  27     does not provide enough packets, empty UDP packets will be sent instead.
  28
  29     \section run Running the example
  30
  31     Running the example is a little bit more complicated since we need to provide example UDP
  32     packets so we can see the application at work. We do this using \c netcat. We open several shell
  33     windows and run the following commands, each in it's own window
  34
  35     The first command listens for incoming UDP packets on port 44345:
  36     <pre>
  37     # nc -u -l -p 44345
  38     </pre>
  39
  40     The next command starts the \c ratestuffer
  41     <pre>
  42     # cd .../Examples/RateStuffer
  43     # scons -u
  44     # ./ratestuffer
  45     </pre>
  46
  47     We should now see '<idle>' messages arriving in the first window once per second. We now can
  48     start another \c netcat to send packets to the input port.
  49
  50     <pre>
  51     # nc -u localhost 44344
  52     < type any text here >
  53     </pre>
  54
  55     Whenever we send out a packet with CR in the last window we should see it appear in the first
  56     one. If we send out packets faster than 1 packet per second, they will start to be discarded if
  57     more than two packets are in flight.
  58
  59     \image html screenshot.png
  60
  61     \section setup Module setup
  62
  63     \image html ratestuffer.png
  64
  65     Above image depicts the module setup implementing the rate stuffer. A
  66     senf::ppi::module::ActiveSocketReader reads the incoming UDP packets and sends them into a
  67     senf::ppi::module::PassiveQueue.
  68
  69     The \a queue feeds the packets into a senf::ppi::module::PriorityJoin. The CloneSource
  70     \a generator is fed as second input into the \a join to provide the stuffing packets.
  71
  72     The RateFilter \a rateFilter reads packets from it's input at a fixed rate and writes them into
  73     the senf::ppi::module::PassiveSocketWriter \a udpWriter. The senf::ppi::module::PriorityJoin
  74     ensures that read requests of the RateStuffer's input are always serviced, either from the \a
  75     queue or, if the \a queue output is throttled, from the \a generator.
  76
  77     \section code Example code
  78
  79     \dontinclude ratestuffer.cc
  80
  81     The code starts out including the necessary header files
  82
  83     \skip Custom
  84     \skip #include
  85     \until Setup
  86
  87     We also define some namespace aliases
  88
  89     \skip namespace
  90     \until senf::ppi;
  91
  92     The RateStuffer application is based on one additional application module.
  93
  94     \subsection ratefilter The RateFilter module
  95
  96     The RateFilter module simply forwards packets at a fixed rate.
  97
  98     \skip class
  99     \until };
 100
 101     Both connectors of the RateFilter module are active. The module is driven by a
 102     senf::ppi::IntervalTimer.
 103
 104     \until }
 105
 106     The event is initialized to fire eery \a interval nanoseconds.  The traffic is routed 'across'
 107     the timer which controls the traffic. The timer is then registered to call
 108     RateFilter::timeout().
 109
 110     \until }
 111
 112     The event handler is quite simple: Every \a interval nanoseconds a packet is read from \a input
 113     and forwarded to \a output.
 114
 115     This is all there is to the RateFilter module. Due to the routing setup, the timer will
 116     automatically be disabled if either \a input or \a output become throttled (which is not even
 117     needed here).
 118
 119     \subsection ratestuffer The RateStuffer subnet
 120
 121     We decide to implement the RateStuffer as a subnet or collection. This is a simple struct or
 122     class which contains all the modules necessary for a specific functionality. The modules are
 123     initialized and connected in the class's constructor. External connectors are exported as
 124     references to the corresponding module connectors:
 125
 126     \skip class
 127     \until rateFilter
 128
 129     First the needed modules are declared. We have
 130     \li the \a barrier to discard incoming packets sent to fast
 131     \li the \a queue to receive incoming packets and create throttling notifications
 132     \li the \a generator to create the stuffing packets
 133     \li the \a join to combine the input stream from the \a queue with the stuffing packet stream
 134     \li the \a rateFilter to generate the fixed rate output stream
 135
 136     \until output
 137
 138     Here we declare the external connectors. The subnetwork exports a single input and output
 139     connector. The external connectors are declared as \e references.
 140
 141     \until output
 142
 143     The constructor now initializes all the local objects. We pass the template \a packet to the \a
 144     generator and set the timing \a interval of the \a rateFilter.
 145
 146     The \a input and \a output connector references are bound to the corresponding connectors we
 147     want to expose: \a input to the \a queue's \a input and \a output to the \a rateStuffer's \a
 148     output.
 149
 150     \until };
 151
 152     The constructor body sets up the connections within the subnetwork. Finally, we set the queueing
 153     discipline of the \a queue. This Completes the RateStuffer. This subnetwork can now be used like
 154     a module.
 155
 156     \subsection main Connecting the modules
 157
 158     The applications main() method starts out by initializing the socket handles
 159
 160     \skip main
 161     \until 44345
 162
 163     The \a inputSocket is listening on port 44344 while the \a outputSocket will send packets to
 164     port 44345 on localhost. The \a outputSocket uses the senf::ConnectedUDPv4SocketProtocol which
 165     is compatible with the senf::ppi::module::PassiveSocketWriter module.
 166
 167     \until udpWriter
 168
 169     Here we allocate the components:
 170
 171     \li \a udpReader to read the packets from \a inputSocket
 172     \li \a stuffer for the real work and
 173     \li \a udpWriter to send the packets to \a outputSocket
 174
 175     \until udpWriter
 176
 177     The \ref senf::ppi::connect() calls setup the necessary connections.
 178
 179     \until run
 180
 181     The module setup is complete, \ref senf::ppi::run() is called to enter the event loop.
 182
 183     \until }
 184  */
 185
 186 \f
 187 // Local Variables:
 188 // mode: c++
 189 // fill-column: 100
 190 // comment-column: 40
 191 // c-file-style: "senf"
 192 // indent-tabs-mode: nil
 193 // ispell-local-dictionary: "american"
 194 // compile-command: "scons -u doc"
 195 // mode: flyspell
 196 // mode: auto-fill
 197 // End: