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.
24 \brief DebugModules public header */
26 #ifndef HH_DebugModules_
27 #define HH_DebugModules_ 1
31 #include "../Utils/safe_bool.hh"
32 #include "../Packets/Packets.hh"
34 #include "ActiveFeeder.hh"
35 #include "../Utils/Logger/SenfLog.hh"
37 //#include "DebugModules.mpp"
38 ///////////////////////////////hh.p////////////////////////////////////////
45 /** \namespace senf::ppi::module::debug
48 This namespace collects several modules helpful for PPI debugging. The modules allow to
49 manually pass packets into a network and read back the output packets.
51 There are three categories of modules:
53 \li <i>Active modules</i> (ActiveSource, ActiveSink) are triggered by external
54 calls. Calling \c submit() / \c request() will send the request into the module network
55 synchronously. From this it follows, that senf::ppi::run() should \e not be
56 called. Instead senf::ppi::init() is used to initialize the network and explicit calls
57 to the active debug modules drive the execution.
58 \li <i>Passive modules</i> (PassiveSource, PassiveSink) contain a queue to save packets
59 (either packets to be transmitted or packets received) and are driven by the network.
60 \li <i>Feeder (almost-)modules</i> (ActiveFeederSource, ActiveFeederSink) are a hybrid of
61 both types of modules: They contain a packet queue but actively drive the network and
62 are used together with senf::ppi::run(). senf::ppi::run() will automatically terminate
63 if all available packets have been processed. These are not modules, they are
64 collections combining a passive debug module and a senf::ppi::ActiveFeeder.
67 /** \brief Debug packet source with active output
69 This module provides packets into the network. Each call to submit() will process the packet
72 \note This module should not be used together with senf::ppi::run(). Instead use
73 senf::ppi::init() and explicit submit() calls. It follows, that <em>no events will be
74 signaled in the network</em>.
78 public safe_bool<ActiveSource>
80 SENF_PPI_MODULE(ActiveSource);
83 connector::ActiveOutput output;
87 void submit(Packet packet); ///< Submit packet
88 /**< \pre boolean_test() is \c true */
90 bool boolean_test() const; ///< \c true if \a output is not throttled
93 /** \brief Debug packet source with passive output
95 This module provides a queue of packets for reading by the network. Each submit() call adds
96 a packet to the queue which will be sent into the network when requested. The output is
97 automatically throttled when the queue becomes empty.
102 SENF_PPI_MODULE(PassiveSource);
104 typedef std::deque<Packet> Queue;
107 typedef Queue::size_type size_type;
109 connector::PassiveOutput output;
113 void throttle(); ///< Throttle output connector
114 void unthrottle(); ///< Unthrottle output connector
116 void submit(Packet packet); ///< Enqueue packet
118 bool empty(); ///< \c true if queue is empty
119 size_type size(); ///< Number of packets in queue
128 /** \brief Debug packet sink with active input
130 This module requests packets from the network. Each call to request() will pass a packet
131 request into the network.
133 \note This module should not be used together with senf::ppi::run(). Instead use
134 senf::ppi::init() and explicit request() calls. It follows, that <em>no events will be
135 signaled in the network</em>.
139 public safe_bool<ActiveSink>
141 SENF_PPI_MODULE(ActiveSink);
144 connector::ActiveInput input;
148 Packet request(); ///< Request packet
149 /**< \pre boolean_test() is \c true */
151 bool boolean_test() const; ///< \c true, if \a input is not throttled
154 /** \brief Debug packet sink with passive input
156 This module provides a queue for the network to write packets into. The packets can then
162 SENF_PPI_MODULE(PassiveSink);
164 typedef std::deque<Packet> Queue;
167 typedef Queue::size_type size_type;
168 typedef Queue::const_iterator iterator;
170 connector::PassiveInput input;
174 void throttle(); ///< Throttle input connection
175 void unthrottle(); ///< Unthrottle input connection
177 bool empty(); ///< \c true, if queue is empty
178 size_type size(); ///< number of packets in the queue
179 iterator begin(); ///< begin iterator of packets in the queue
180 iterator end(); ///< past-the-end iterator of packets in the queue
182 Packet front(); ///< first packet in the queue
183 Packet pop_front(); ///< remove and return first packet in the queue
185 void clear(); ///< clear the queue
193 /** \brief Active, queue-based packet source
195 The ActiveFeederSource contains a packet queue containing the packets to be precessed. These
196 packets are actively fed into the network when it is run with senf::ppi::run() until it is
197 empty, when senf::ppi::run() will return.
199 \note senf::ppi::run will return as soon as no events are active. If want you want is to
200 precess a set of packets placed into the ActiveFeederSource queue you must make sure,
201 that eventually all events in the module are disabled by throttling or other
202 activities. Otherwise, senf::ppi::run() will \e not return.
204 ActiveFeederSource is not a module but a collection of two modules: a PassiveSource and an
207 class ActiveFeederSource
210 PassiveSource source;
214 typedef PassiveSource::size_type size_type;
216 connector::ActiveOutput & output;
218 ActiveFeederSource();
220 void submit(Packet packet); ///< enqueue packet
221 bool empty(); ///< \c true, if queue is empty
222 size_type size(); ///< number of packets in the queue
225 /** \brief Active, queue-based packet sink
227 The ActiveFeederSink contains a packet queue to receive the packets from the network. The
228 ActiveFeederSink will actively request packets from the network until it's input is
231 \note ActiveFeederSink does \e not have a termination condition like ActiveFeederSource, it
232 relies on the network to throttle it's input. Also, the same not as for
233 ActiveFeederSource applies here too: You need to ensure, that no events are active
234 eventually or senf::ppi::run will not return.
236 ActiveFeederSink is not a module but a collection of two modules: a PassiveSink and an
239 class ActiveFeederSink
246 typedef PassiveSink::size_type size_type;
247 typedef PassiveSink::iterator iterator;
249 connector::ActiveInput & input;
264 /** \brief Log received packets
266 This module will log all packets sent to it's input using SENF_LOG to the given log
267 \a Stream, \a Area and \a Level.
269 template < class Stream = log::Debug,
270 class Area = log::DefaultArea,
271 class Level = log::VERBOSE >
273 : public module::Module
275 SENF_PPI_MODULE(LogSink);
278 connector::PassiveInput input;
288 ///////////////////////////////hh.e////////////////////////////////////////
289 #include "DebugModules.cci"
290 //#include "DebugModules.ct"
291 #include "DebugModules.cti"
298 // comment-column: 40
299 // c-file-style: "senf"
300 // indent-tabs-mode: nil
301 // ispell-local-dictionary: "american"
302 // compile-command: "scons -u test"