4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
23 /** \mainpage RateStuffer: A simple example featuring the Packet Processing Infrastructure
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.
29 \section run Running the example
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
35 The first command listens for incoming UDP packets on port 44345:
40 The next command starts the \c ratestuffer
42 # cd .../Examples/RateStuffer
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.
51 # nc -u localhost 44344
52 < type any text here >
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.
59 \image html screenshot.png
61 \section setup Module setup
63 \image html ratestuffer.png
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 (via a senf::ppi::module::ThrottleBarrier).
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.
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.
77 The \a barrier is not strictly necessary. However, it makes the behavior of the RateStuffer
78 predictable in the case where packets need to be dropped. Without the
79 senf::ppi::module::ThrottleBarrier, the packets will be left in the kernel socket queue. Packets
80 will only start to be dropped when that queue fills up. The size of this queue cannot be easily
81 manipulated and it's initial size is immense. So to stop the kernel queue from filling up with
82 increasingly out-of-date packets, we add the \a barrier which will explicitly read and drop
85 \section code Example code
87 \dontinclude ratestuffer.cc
89 The code starts out including the necessary header files
95 We also define some namespace aliases
100 The RateStuffer application is based on one additional application module.
102 \subsection ratefilter The RateFilter module
104 The RateFilter module simply forwards packets at a fixed rate.
109 Both connectors of the RateFilter module are active. The module is driven by a
110 senf::ppi::IntervalTimer.
114 The event is initialized to fire eery \a interval nanoseconds. The traffic is routed 'across'
115 the timer which controls the traffic. This routing lets the module automatically handle
116 throttling events. The timer is registered to call RateFilter::timeout().
120 The event handler is quite simple: Every \a interval nanoseconds a packet is read from \a input
121 and forwarded to \a output.
123 This is all there is to the RateFilter module. Due to the routing setup, the timer will
124 automatically be disabled should either \a input or \a output become throttled. However, in this
125 specific case this should never happen: The \a input is connected (via the \a join) to the
126 senf::ppi::module::CloneSource, which will never throttle. The \a output is connected to a UDP
127 socket which also never throttles.
129 \subsection ratestuffer The RateStuffer subnet
131 We decide to implement the RateStuffer as a subnet or collection. This is a simple struct or
132 class which contains all the modules necessary for a specific functionality. The modules are
133 initialized and connected in the class's constructor. External connectors are exported as
134 references to the corresponding module connectors:
139 First the needed modules are declared. We have
140 \li the \a barrier to discard incoming packets sent to fast
141 \li the \a queue to receive incoming packets and create throttling notifications
142 \li the \a generator to create the stuffing packets
143 \li the \a join to combine the input stream from the \a queue with the stuffing packet stream
144 \li the \a rateFilter to generate the fixed rate output stream
148 Here we declare the external connectors. The subnetwork exports a single input and output
149 connector. The external connectors are declared as \e references.
153 The constructor now initializes all the local objects. We pass the template \a packet to the \a
154 generator and set the timing \a interval of the \a rateFilter.
156 The \a input and \a output connector references are bound to the corresponding connectors we
157 want to expose: \a input to the \a barrier's \a input and \a output to the \a rateFilter's \a
162 The constructor body sets up the connections within the subnetwork. Finally, we set the queueing
163 discipline of the \a queue. This Completes the RateStuffer. This subnetwork can now be used like
166 \subsection main Application setup
168 The applications main() method starts out by initializing the socket handles
173 The \a inputSocket is listening on port 44344 while the \a outputSocket will send packets to
174 port 44345 on localhost. The \a outputSocket uses the senf::ConnectedUDPv4SocketProtocol which
175 is compatible with the senf::ppi::module::PassiveSocketWriter module.
179 Here we allocate the components:
181 \li \a udpReader to read the packets from \a inputSocket
182 \li \a stuffer for the real work and
183 \li \a udpWriter to send the packets to \a outputSocket
187 The \ref senf::ppi::connect() calls setup the necessary connections.
189 The module setup is complete, \ref senf::ppi::run() is called to enter the event loop.
198 // comment-column: 40
199 // c-file-style: "senf"
200 // indent-tabs-mode: nil
201 // ispell-local-dictionary: "american"
202 // compile-command: "scons -u doc"