4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
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 using namespace senf::ppi::module;
25 /** \mainpage Example introducing the Packet Processing Infrastructure
27 This example application implements a simple PPI application: It will read UDP packets from an
28 input port and will forward them to another port at a fixed packet rate. If the input stream
29 does not provide enough packets, empty UDP packets will be sent instead.
31 \section run Running the example
33 Running the example is a little bit more complicated since we need to provide example UDP
34 packets so we can see the application at work. We do this using \c netcat. We open several shell
35 windows and run the following commands, each in it's own window
37 The first command listens for incoming UDP packets on port 44345:
42 The next command starts the \c ratestuffer
44 # cd .../Examples/RateStuffer
49 We should now see '<idle>' messages arriving in the first window once per second. We now can
50 start another \c netcat to send packets to the input port.
53 # nc -u localhost 44344
54 < type any text here >
57 Whenever we send out a packet with CR in the last window we should see it appear in the first
58 one. If we send out packets faster than 1 packet per second, they will start to be discarded if
59 more than two packets are in flight.
61 \image html screenshot.png
63 \section setup Module setup
65 \diaimage ratestuffer.dia
67 Above image depicts the module setup implementing the rate stuffer. A
68 senf::ppi::module::ActiveSocketSource reads the incoming UDP packets and sends them into a
69 senf::ppi::module::PassiveQueue (via a senf::ppi::module::ThrottleBarrier).
71 The \a queue feeds the packets into a senf::ppi::module::PriorityJoin. The CloneSource
72 \a generator is fed as second input into the \a join to provide the stuffing packets.
74 The RateFilter \a rateFilter reads packets from it's input at a fixed rate and writes them into
75 the senf::ppi::module::PassiveSocketSink \a udpSink. The senf::ppi::module::PriorityJoin
76 ensures that read requests of the RateStuffer's input are always serviced, either from the \a
77 queue or, if the \a queue output is throttled, from the \a generator.
79 The \a barrier is not strictly necessary. However, it makes the behavior of the RateStuffer
80 predictable in the case where packets need to be dropped. Without the
81 senf::ppi::module::ThrottleBarrier, the packets will be left in the kernel socket queue. Packets
82 will only start to be dropped when that queue fills up. The size of this queue cannot be easily
83 manipulated and it's initial size is immense. So to stop the kernel queue from filling up with
84 increasingly out-of-date packets, we add the \a barrier which will explicitly read and drop
87 \section code Example code
89 \dontinclude ratestuffer.cc
91 The code starts out including the necessary header files
97 We also define some namespace aliases
102 The RateStuffer application is based on one additional application module.
104 \subsection ratefilter The RateFilter module
106 The RateFilter module simply forwards packets at a fixed rate.
111 Both connectors of the RateFilter module are active. The module is driven by a
112 senf::ppi::IntervalTimer.
116 The event is initialized to fire every \a interval nanoseconds. The traffic is routed 'across'
117 the timer which controls the traffic. This routing lets the module automatically handle
118 throttling events. The timer is registered to call RateFilter::timeout().
122 The event handler is quite simple: Every \a interval nanoseconds a packet is read from \a input
123 and forwarded to \a output.
125 This is all there is to the RateFilter module. Due to the routing setup, the timer will
126 automatically be disabled should either \a input or \a output become throttled. However, in this
127 specific case this should never happen: The \a input is connected (via the \a join) to the
128 senf::ppi::module::CloneSource, which will never throttle. The \a output is connected to a UDP
129 socket which also never throttles.
131 \subsection ratestuffer The RateStuffer subnet
133 We decide to implement the RateStuffer as a subnet or collection. This is a simple struct or
134 class which contains all the modules necessary for a specific functionality. The modules are
135 initialized and connected in the class's constructor. External connectors are exported as
136 references to the corresponding module connectors:
141 First the needed modules are declared. We have
142 - the \a barrier to discard incoming packets sent to fast
143 - the \a queue to receive incoming packets and create throttling notifications
144 - the \a generator to create the stuffing packets
145 - the \a join to combine the input stream from the \a queue with the stuffing packet stream
146 - the \a rateFilter to generate the fixed rate output stream
150 Here we declare the external connectors. The subnetwork exports a single input and output
151 connector. The external connectors are declared as \e references.
155 The constructor now initializes all the local objects. We pass the template \a packet to the \a
156 generator and set the timing \a interval of the \a rateFilter.
158 The \a input and \a output connector references are bound to the corresponding connectors we
159 want to expose: \a input to the \a barrier's \a input and \a output to the \a rateFilter's \a
164 The constructor body sets up the connections within the subnetwork. Finally, we set the queueing
165 discipline of the \a queue. This Completes the RateStuffer. This subnetwork can now be used like
168 \subsection main Application setup
170 The applications main() method starts out by initializing the socket handles
175 The \a inputSocket is listening on port 44344 while the \a outputSocket will send packets to
176 port 44345 on localhost. The \a outputSocket uses the senf::ConnectedUDPv4SocketProtocol which
177 is compatible with the senf::ppi::module::PassiveSocketSink module.
181 Here we allocate the components:
183 - \a udpSource to read the packets from \a inputSocket
184 - \a stuffer for the real work and
185 - \a udpSink to send the packets to \a outputSocket
189 The \ref senf::ppi::connect() calls setup the necessary connections.
191 The module setup is complete, \ref senf::ppi::run() is called to enter the event loop.
200 // comment-column: 40
201 // c-file-style: "senf"
202 // indent-tabs-mode: nil
203 // ispell-local-dictionary: "american"
204 // compile-command: "scons -u doc"