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.
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 \section code Example code
79 \dontinclude ratestuffer.cc
81 The code starts out including the necessary header files
87 We also define some namespace aliases
92 The RateStuffer application is based on one additional application module.
94 \subsection ratefilter The RateFilter module
96 The RateFilter module simply forwards packets at a fixed rate.
101 Both connectors of the RateFilter module are active. The module is driven by a
102 senf::ppi::IntervalTimer.
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().
112 The event handler is quite simple: Every \a interval nanoseconds a packet is read from \a input
113 and forwarded to \a output.
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
119 \subsection ratestuffer The RateStuffer subnet
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:
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
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.
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.
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
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
156 \subsection main Connecting the modules
158 The applications main() method starts out by initializing the socket handles
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.
169 Here we allocate the components:
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
177 The \ref senf::ppi::connect() calls setup the necessary connections.
181 The module setup is complete, \ref senf::ppi::run() is called to enter the event loop.
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"