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.
24 \brief DebugModules public header */
26 #ifndef HH_SENF_PPI_DebugModules_
27 #define HH_SENF_PPI_DebugModules_ 1
31 #include <senf/Utils/safe_bool.hh>
32 #include "MonitorModule.hh"
33 #include "ActiveFeeder.hh"
34 #include <senf/Utils/Logger/SenfLog.hh>
36 //#include "DebugModules.mpp"
37 //-/////////////////////////////////////////////////////////////////////////////////////////////////
44 /** \namespace senf::ppi::module::debug
47 This namespace collects several modules helpful for PPI debugging. The modules allow to
48 manually pass packets into a network and read back the output packets.
50 There are three categories of modules:
52 \li <i>Active modules</i> (ActiveSource, ActiveSink) are triggered by external
53 calls. Calling \c submit() / \c request() will send the request into the module network
54 synchronously. From this it follows, that senf::ppi::run() should \e not be
55 called. Instead senf::ppi::init() is used to initialize the network and explicit calls
56 to the active debug modules drive the execution.
57 \li <i>Passive modules</i> (PassiveSource, PassiveSink) contain a queue to save packets
58 (either packets to be transmitted or packets received) and are driven by the network.
59 \li <i>Feeder (almost-)modules</i> (ActiveFeederSource, ActiveFeederSink) are a hybrid of
60 both types of modules: They contain a packet queue but actively drive the network and
61 are used together with senf::ppi::run(). senf::ppi::run() will automatically terminate
62 if all available packets have been processed. These are not modules, they are
63 collections combining a passive debug module and a senf::ppi::ActiveFeeder.
66 /** \brief Debug packet source with active output
68 This module provides packets into the network. Each call to submit() will process the packet
71 \note This module should not be used together with senf::ppi::run(). Instead use
72 senf::ppi::init() and explicit submit() calls. It follows, that <em>no events will be
73 signaled in the network</em>.
77 public safe_bool<ActiveSource>
79 SENF_PPI_MODULE(ActiveSource);
82 connector::ActiveOutput<> output;
86 void submit(Packet const & packet); ///< Submit packet
87 /**< \pre boolean_test() is \c true */
89 bool boolean_test() const; ///< \c true if \a output is not throttled
92 /** \brief Debug packet source with passive output
94 This module provides a queue of packets for reading by the network. Each submit() call adds
95 a packet to the queue which will be sent into the network when requested. The output is
96 automatically throttled when the queue becomes empty.
101 SENF_PPI_MODULE(PassiveSource);
103 typedef std::deque<Packet> Queue;
106 typedef Queue::size_type size_type;
108 connector::PassiveOutput<> output;
112 void throttle(); ///< Throttle output connector
113 void unthrottle(); ///< Unthrottle output connector
115 void submit(Packet const & packet); ///< Enqueue packet
117 bool empty(); ///< \c true if queue is empty
118 size_type size(); ///< Number of packets in queue
122 virtual void v_init();
127 /** \brief Debug packet sink with active input
129 This module requests packets from the network. Each call to request() will pass a packet
130 request into the network.
132 \note This module should not be used together with senf::ppi::run(). Instead use
133 senf::ppi::init() and explicit request() calls. It follows, that <em>no events will be
134 signaled in the network</em>.
138 public safe_bool<ActiveSink>
140 SENF_PPI_MODULE(ActiveSink);
143 connector::ActiveInput<> input;
147 Packet request(); ///< Request packet
148 /**< \pre boolean_test() is \c true */
150 bool boolean_test() const; ///< \c true, if \a input is not throttled
153 /** \brief Debug packet sink with passive input
155 This module provides a queue for the network to write packets into. The packets can then
161 SENF_PPI_MODULE(PassiveSink);
163 typedef std::deque<Packet> Queue;
166 typedef Queue::size_type size_type;
167 typedef Queue::const_iterator iterator;
169 connector::PassiveInput<> input;
173 void throttle(); ///< Throttle input connection
174 void unthrottle(); ///< Unthrottle input connection
176 bool empty(); ///< \c true, if queue is empty
177 size_type size(); ///< number of packets in the queue
178 iterator begin(); ///< begin iterator of packets in the queue
179 iterator end(); ///< past-the-end iterator of packets in the queue
181 Packet front(); ///< first packet in the queue
182 Packet pop_front(); ///< remove and return first packet in the queue
184 void clear(); ///< clear the queue
192 /** \brief Active, queue-based packet source
194 The ActiveFeederSource contains a packet queue containing the packets to be processed. These
195 packets are actively fed into the network when it is run with senf::ppi::run() until it is
196 empty, when senf::ppi::run() will return.
198 \note senf::ppi::run will return as soon as no events are active. If want you want is to
199 Process a set of packets placed into the ActiveFeederSource queue you must make sure,
200 that eventually all events in the module are disabled by throttling or other
201 activities. Otherwise, senf::ppi::run() will \e not return.
203 ActiveFeederSource is not a module but a collection of two modules: a PassiveSource and an
206 class ActiveFeederSource
209 PassiveSource source;
213 typedef PassiveSource::size_type size_type;
215 connector::ActiveOutput<> & output;
217 ActiveFeederSource();
219 void submit(Packet packet); ///< enqueue packet
220 bool empty(); ///< \c true, if queue is empty
221 size_type size(); ///< number of packets in the queue
224 /** \brief Active, queue-based packet sink
226 The ActiveFeederSink contains a packet queue to receive the packets from the network. The
227 ActiveFeederSink will actively request packets from the network until it's input is
230 \note ActiveFeederSink does \e not have a termination condition like ActiveFeederSource, it
231 relies on the network to throttle it's input. Additionally, the restrictions of
232 ActiveFeederSource apply here too: You need to ensure, that no (additional) events are
233 active (eventually) or senf::ppi::run will not return.
235 ActiveFeederSink is not a module but a collection of two modules: a PassiveSink and an
238 class ActiveFeederSink
245 typedef PassiveSink::size_type size_type;
246 typedef PassiveSink::iterator iterator;
248 connector::ActiveInput<> & input;
263 /** \brief Log received packets
265 This module will %log all packets sent to it's input using SENF_LOG to the given %log
266 \a Stream, \a Area and \a Level.
268 template < class Stream = log::Debug,
269 class Area = log::DefaultArea,
270 class Level = log::VERBOSE >
272 : public MonitorModule<>
274 SENF_PPI_MODULE(Logger);
277 explicit Logger(std::string label);
280 virtual void v_handlePacket(Packet const & packet);
287 //-/////////////////////////////////////////////////////////////////////////////////////////////////
288 #include "DebugModules.cci"
289 //#include "DebugModules.ct"
290 #include "DebugModules.cti"
297 // comment-column: 40
298 // c-file-style: "senf"
299 // indent-tabs-mode: nil
300 // ispell-local-dictionary: "american"
301 // compile-command: "scons -u test"