0dfe9cfafaf797b720c54ea15456a4c0e16fd8c7
[senf.git] / senf / PPI / Connectors.hh
1 // $Id$
2 //
3 // Copyright (C) 2007
4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 //     Stefan Bund <g0dil@berlios.de>
7 //
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.
12 //
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.
17 //
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.
22
23 /** \file
24     \brief Connectors public header */
25
26 #ifndef HH_SENF_PPI_Connectors_
27 #define HH_SENF_PPI_Connectors_ 1
28
29 // Custom includes
30 #include <deque>
31 #include <boost/utility.hpp>
32 #include <boost/scoped_ptr.hpp>
33 #include <senf/Utils/safe_bool.hh>
34 #include <senf/Utils/Exception.hh>
35 #include <senf/Packets/Packets.hh>
36 #include "predecl.hh"
37 #include "detail/Callback.hh"
38 #include "Queueing.hh"
39 #include "ModuleManager.hh"
40
41 //#include "Connectors.mpp"
42 ///////////////////////////////hh.p////////////////////////////////////////
43
44 namespace senf {
45 namespace ppi {
46 namespace connector {
47
48     /** \namespace senf::ppi::connector
49         \brief Connector classes
50
51         A connector has three independent properties
52         \li it may be \e active or \e passive
53         \li it may be an \e input or an \e output
54         \li it has an (optional) packet type
55
56         \e Active connectors are activated from within the module, \e passive connectors are
57         signaled by the external framework. \e Input connectors receive packets, \e output
58         connectors send packets.
59
60         All passive connectors call some onRequest callback whenever I/O needs to be performed. All
61         input connectors possess a packet queue.
62
63         We therefore have 4 connector types each of which is parameterized by the type of packet
64         traversing the connector:
65         \li senf::ppi::connector::ActiveInput
66         \li senf::ppi::connector::ActiveOutput 
67         \li senf::ppi::connector::PassiveInput 
68         \li senf::ppi::connector::PassiveOutput.
69
70         Connectors are declared as module data members and are then externally connected to other
71         modules.
72
73         The connectors each take an optional template argument. If this argument is specified, it
74         must be the type of packet expected or sent on this connector. If it is not specified,
75         packets will be passed using the generic Packet handle.
76
77         \code
78         class IpFilter : public senf::ppi::module::Module
79         {
80             SENF_PPI_MODULE(SomeModule);
81
82         public:
83             senf::ppi::connector::ActiveInput<senf::EthernetPacket> input;
84             senf::ppi::connector::PassiveOutput<senf::IpPacket> output;
85
86             IpFilter() {
87                 route(input, output);
88                 input.onRequest(&IpFilter::onRequest);
89             }
90
91         private:
92             void onRequest() {
93                 // 'input()' will return a senf::EthernetPacket packet handle
94                 try { output( input().find<senf::IpPacket>() ); }
95                 catch (senf::InvalidPacketChainException & ex) { ; }
96             }
97         };
98         \endcode
99
100
101         \section ppi_jacks Jacks
102
103         A Jack is a packet type aware and possibly packet type converting reference to an arbitrary
104         connector of the same type. Jacks are used in groups to indirectly declare the input's and
105         output's
106
107         \code
108         class MyGroup
109         {
110         private:
111             senf::ppi::module::PassiveQueue queue;
112             senf::ppi::module::RateAnalyzer analyzer;
113
114         public:
115             senf::ppi::connector::ActiveInputJack<senf::EthernetPacket> input;
116             senf::ppi::connector::ActiveOutputJack<senf::EthernetPacket> output;
117
118             MyGroup() 
119                 : queue (), analyzer (), input (queue.input), output (analyzer.output)
120             {
121                 senf::ppi::connect(queue, analyzer);
122             }
123         };
124         \endcode
125
126         The jacks are initialized by passing an arbitrary compatible connector to the jack
127         constructor. A connector is compatible, if
128         \li It has the same input/output active/passive specification
129         \li Either the Jack or the Connector are generic (senf::Packet) or Jack and Connector have
130             the same packet type
131
132         Jacks can be used wherever connectors may be used. Jacks may be defined anywhere, not only
133         in modules. It is however important to ensure that the lifetime of the jack does not exceed
134         the lifetime of the referenced connector.
135
136         \see
137             senf::ppi::module::Module \n
138             senf::ppi::connect() \n
139             \ref ppi_connectors
140      */
141
142     /** \brief Incompatible connectors connected
143
144         This exception is thrown, when two incompatible connectors are connected. This happens if
145         both connectors of a senf::ppi::connect() statement declare a packet type (the connector
146         template argument) but they don't declare the same packet type.
147
148         You need to ensure, that both connectors use the same packet type.
149
150         \see senf::ppi::connect()
151      */
152     struct IncompatibleConnectorsException : public senf::Exception
153     { IncompatibleConnectorsException() : senf::Exception("Incompatible connectors") {} };
154
155     /** \brief Connector base-class
156
157         This connector provides access to the generic connector facilities. This includes the
158         connection management (access to the connected peer) and the containment management (access
159         to the containing module)
160      */
161     class Connector
162         : ModuleManager::Initializable, boost::noncopyable
163     {
164         SENF_LOG_CLASS_AREA();
165         SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
166     public:
167         Connector & peer() const;       ///< Get peer connected to this connector
168         module::Module & module() const; ///< Get this connectors containing module
169
170         bool connected() const;         ///< \c true, if connector connected, \c false otherwise
171
172         void disconnect();              ///< Disconnect connector from peer
173
174         enum TraceState { NO_TRACING, TRACE_IDS, TRACE_CONTENTS };
175
176         static void tracing(TraceState state);
177         static TraceState tracing();
178
179     protected:
180         Connector();
181         virtual ~Connector();
182
183         void connect(Connector & target);
184
185         void trace(Packet const & p, char const * label);
186         void throttleTrace(char const * label, char const * type);
187
188         void unregisterConnector();
189         
190     private:
191         virtual std::type_info const & packetTypeID();
192         
193         virtual void v_disconnected() const;
194
195         void setModule(module::Module & module);
196
197         Connector * peer_;
198         module::Module * module_;
199
200         static TraceState traceState_;
201
202         friend class module::Module;
203     };
204
205     /** \brief Passive connector base-class
206
207         A passive connector is a connector which is activated externally whenever an I/O request
208         occurs. Passive connectors are the origin of throttling notifications. Depending on the type
209         of connector (output or input) the respective throttling is called forward or backward
210         throttling.
211
212         Passive connectors always handle two throttling states:
213
214         - The \e native throttling state is set manually by the module. It is the throttling state
215             originating in the current module
216         - The \e forwarded throttling state is the state as it is received by throttling
217             notifications
218
219         The accumulative throttling state is generated by combining all sub-states.
220      */
221     class PassiveConnector
222         : public virtual Connector
223     {
224     public:
225         ~PassiveConnector();
226
227         template <class Handler>
228         void onRequest(Handler handler);///< Register I/O event handler
229                                         /**< The registered handler will be called, whenever packets
230                                              arrive or should be generated by the module depending
231                                              on the connector type (input or output). The \a handler
232                                              argument is either an arbitrary callable object or it
233                                              is a pointer-to-member to a member of the class which
234                                              holds this input. In the second case, the pointer will
235                                              automatically be bound to the containing instance.
236
237                                              \param[in] handler Handler to call, whenever an I/O
238                                                  operation is to be performed. */
239
240
241         bool throttled() const;         ///< Get accumulative throttling state
242         bool nativeThrottled() const;   ///< Get native throttling state
243
244         void throttle();                ///< Set native throttling
245         void unthrottle();              ///< Revoke native throttling
246
247         ActiveConnector & peer() const;
248
249     protected:
250         PassiveConnector();
251
252         void emit();
253
254     private:
255         virtual void v_init();
256
257         // Called by the routing to change the throttling state from forwarding routes
258         void notifyThrottle();          ///< Forward a throttle notification to this connector
259         void notifyUnthrottle();        ///< Forward an unthrottle notification to this connector
260
261         // Internal members to emit throttling notifications to the connected peer
262         void emitThrottle();
263         void emitUnthrottle();
264
265         // Called after unthrottling the connector
266         virtual void v_unthrottleEvent();
267
268         // called by ForwardingRoute to register a new route
269         void registerRoute(ForwardingRoute & route);
270         void unregisterRoute(ForwardingRoute & route);
271
272         typedef ppi::detail::Callback<>::type Callback;
273         Callback callback_;
274
275         bool remoteThrottled_;
276         bool nativeThrottled_;
277
278         typedef std::vector<ForwardingRoute*> Routes;
279         Routes routes_;
280
281         friend class senf::ppi::ForwardingRoute;
282     };
283
284     /** \brief Active connector base-class
285
286         An active connector is a connector which emits I/O requests. Active connectors receive
287         throttling notifications. Depending on the type of connector (input or output) the
288         respective throttling is called forward or backward throttling.
289
290         Active connectors do not handle any throttling state, they just receive the
291         notifications. These notifications should then either be processed by the module or be
292         forwarded to other connectors.
293      */
294     class ActiveConnector
295         : public virtual Connector
296     {
297         typedef ppi::detail::Callback<>::type Callback;
298     public:
299         ~ActiveConnector();
300
301         template <class Handler>
302         void onThrottle(Handler handler); ///< Register throttle notification handler
303                                         /**< The handler register here will be called, whenever a
304                                              throttle notification comes in. The \a handler argument
305                                              is either an arbitrary callable object or it is a
306                                              pointer-to-member to a member of the class which holds
307                                              this input. In the second case, the pointer will
308                                              automatically be bound to the containing instance.
309
310                                              \param[in] handler Handler to call on throttle
311                                                  notifications. */
312         void onThrottle();              ///< Clear throttle notification handler
313
314         template <class Handler>
315         void onUnthrottle(Handler handler); ///< Register unthrottle notification handler
316                                         /**< The handler register here will be called, whenever an
317                                              unthrottle notification comes in. The \a handler
318                                              argument is either an arbitrary callable object or it
319                                              is a pointer-to-member to a member of the class which
320                                              holds this input. In the second case, the pointer will
321                                              automatically be bound to the containing instance.
322
323                                              \param[in] handler Handler to call on unthrottle
324                                                  notifications. */
325         void onUnthrottle();            ///< Clear unthrottle notification handler
326
327         bool throttled() const;         ///< \c true, if peer() is throttled
328
329         PassiveConnector & peer() const;
330
331     protected:
332         ActiveConnector();
333
334     private:
335         virtual void v_init();
336
337         // called by the peer() to forward throttling notifications
338         void notifyThrottle();
339         void notifyUnthrottle();
340
341         // called by ForwardingRoute to register a new route
342         void registerRoute(ForwardingRoute & route);
343         void unregisterRoute(ForwardingRoute & route);
344
345         Callback throttleCallback_;
346         Callback unthrottleCallback_;
347
348         typedef std::vector<ForwardingRoute*> NotifyRoutes;
349         NotifyRoutes notifyRoutes_;
350
351         bool throttled_;        
352
353         friend class senf::ppi::ForwardingRoute;
354         friend class PassiveConnector;
355     };
356
357     /** \brief Input connector base-class
358
359         An input connector receives packets. It may be either an ActiveConnector or a
360         PassiveConnector. An input connector contains a packet queue. This queue enables processing
361         packets in batches or generating multiple output packets from a single input packet. The
362         queues have the potential to greatly simplify the module implementations.
363
364         \implementation Which container to use?
365             \li list has good insertion and deletion properties on both ends but it costs a dynamic
366                 memory allocation for every insertion. A very good property is, that iterators stay
367                 valid across insertions/deletions
368             \li vector is fast and has good amortized dynamic allocation properties. However, it is
369                 quite unusable as a queue
370             \li deque has comparable dynamic allocation properties as vector but also has good
371                 insertion/removal properties on both ends.
372
373             So probably we will use a deque. I'd like a container which keeps iterators intact on
374             insertion/deletion but I believe that list is just to expensive since every packet will
375             be added to the queue before it can be processed.
376      */
377     class InputConnector
378         : public virtual Connector
379     {
380         typedef std::deque<Packet> Queue;
381     public:
382         typedef Queue::const_iterator queue_iterator; ///< Iterator type of the embedded queue
383         typedef Queue::size_type size_type; ///< Unsigned type for counting queue elements
384
385
386         Packet operator()();            ///< Get a packet
387                                         /**< This member is the primary method to access received
388                                              data. On passive connectors, this operator will just
389                                              dequeue a packet from the packet queue. If the
390                                              connector is active, the connector will request new
391                                              packets from the connected module. If the packet
392                                              request cannot be fulfilled, this is considered to be a
393                                              logic error in the module implementation and an
394                                              exception is raised. */
395
396         Packet read();                  ///< Alias for operator()()
397
398         OutputConnector & peer() const;
399
400         queue_iterator begin() const;   ///< Access queue begin (head)
401         queue_iterator end() const;     ///< Access queue past-the-end (tail)
402         Packet peek() const;            ///< Return head element from the queue
403
404         size_type queueSize() const;    ///< Return number of elements in the queue
405         bool empty() const;             ///< Return queueSize() == 0
406
407     protected:
408         InputConnector();
409
410     private:
411         void enqueue(Packet const & p);
412
413         virtual void v_requestEvent();
414         virtual void v_enqueueEvent();
415         virtual void v_dequeueEvent();
416
417         Queue queue_;
418
419         friend class OutputConnector;
420     };
421
422     /** \brief Output connector base-class
423
424         An output connector sends out packets. It may be either an ActiveConnector or a
425         PassiveConnector. An output connector does \e not have an built-in queueing, it relies on
426         the queueing of the connected input.
427      */
428     class OutputConnector
429         : public virtual Connector
430     {
431     public:
432         void operator()(Packet const & p);      ///< Send out a packet
433
434         void write(Packet const & p);           ///< Alias for operator()(Packet p)
435
436         InputConnector & peer() const;
437
438     protected:
439         OutputConnector();
440     };
441
442     /** \brief Combination of PassiveConnector and InputConnector
443
444         The GenericPassiveInput automatically controls the connectors throttling state using a
445         queueing discipline. The standard queueing discipline is ThresholdQueueing, which throttles
446         the connection whenever the queue length reaches the high threshold and unthrottles the
447         connection when the queue reaches the low threshold. The default queueing discipline is
448         <tt>ThresholdQueueing(1,0)</tt> which will throttle the input whenever the queue is
449         non-empty.
450      */
451     class GenericPassiveInput
452         : public PassiveConnector, public InputConnector,
453           public safe_bool<GenericPassiveInput>
454     {
455     public:
456         GenericActiveOutput & peer() const;
457
458         bool boolean_test() const;      ///< \c true, if ! empty()
459
460         template <class QDisc>
461         void qdisc(QDisc const & disc); ///< Change the queueing discipline
462                                         /**< The queueing discipline is a class which provides the
463                                              QueueingDiscipline interface.
464
465                                              \param[in] disc New queueing discipline */
466
467     protected:
468         GenericPassiveInput();
469
470     private:
471         void v_enqueueEvent();
472         void v_dequeueEvent();
473         void v_unthrottleEvent();
474
475         boost::scoped_ptr<QueueingDiscipline> qdisc_;
476     };
477
478     /** \brief Combination of PassiveConnector and OutputConnector
479      */
480     class GenericPassiveOutput
481         : public PassiveConnector, public OutputConnector,
482           public safe_bool<GenericPassiveOutput>
483     {
484     public:
485         GenericActiveInput & peer() const;
486
487         bool boolean_test() const;      ///< Always \c true
488
489         void connect(GenericActiveInput & target); ///< Internal: Use senf::ppi::connect() instead
490
491         friend class GenericActiveInput;
492
493     protected:
494         GenericPassiveOutput();
495
496     };
497
498     /** \brief Combination of ActiveConnector and InputConnector
499      */
500     class GenericActiveInput
501         : public ActiveConnector, public InputConnector,
502           public safe_bool<GenericActiveInput>
503     {
504     public:
505         GenericPassiveOutput & peer() const;
506
507         bool boolean_test() const;      ///< \c true, if ! empty() or ! throttled()
508
509         void request();                 ///< request more packets without dequeuing any packet
510
511     protected:
512         GenericActiveInput();
513
514     private:
515         void v_requestEvent();
516     };
517
518     /** \brief Combination of ActiveConnector and OutputConnector
519      */
520     class GenericActiveOutput
521         : public ActiveConnector, public OutputConnector,
522           public safe_bool<GenericActiveOutput>
523     {
524     public:
525         GenericPassiveInput & peer() const;
526
527         bool boolean_test() const;      ///< \c true if peer() is ! throttled()
528
529         void connect(GenericPassiveInput & target); ///< Internal: Use senf::ppi::connect() instead
530
531     protected:
532         GenericActiveOutput();
533
534     };
535
536 #ifndef DOXYGEN
537
538 #   define TypedConnector_Input read
539 #   define TypedConnector_Output write
540 #   define TypedConnector(pType, dir)                                                             \
541         template <class PacketType>                                                               \
542         class pType ## dir                                                                        \
543             : public Generic ## pType ## dir,                                                     \
544               private detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>        \
545         {                                                                                         \
546             typedef detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType> mixin;   \
547         public:                                                                                   \
548             using mixin::operator();                                                              \
549             using mixin::TypedConnector_ ## dir ;                                                 \
550         private:                                                                                  \
551             virtual std::type_info const & packetTypeID()                                         \
552                 { return typeid(typename PacketType::type); }                                     \
553             friend class detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>;    \
554         };                                                                                        \
555         template <>                                                                               \
556         class pType ## dir <Packet> : public Generic ## pType ## dir                              \
557         {}
558
559     TypedConnector( Passive, Input  );
560     TypedConnector( Passive, Output );
561     TypedConnector( Active,  Input  );
562     TypedConnector( Active,  Output );
563
564 #   undef TypedConnector
565 #   undef TypedConnector_Input
566 #   undef TypedConnector_Output
567
568 #else
569
570     /** \brief Connector actively reading packets
571         
572         \tparam PacketType Type of packet to read. Defaults to senf::Packet
573
574         The %ActiveInput %connector template reads data actively from a connected %module. This
575         class is completely implemented via it's base-class, GenericActiveInput, the only 
576         difference is that read packets are returned as \a PacketType instead of generic 
577         senf::Packet references.
578
579         \see GenericActiveInput \n
580             senf::ppi::connector
581      */
582     template <class PacketType=Packet>
583     class ActiveInput : public GenericActiveInput
584     {
585     public:
586         PacketType operator()();        ///< Read packet
587                                         /**< \throws std::bad_cast if the %connector receives a
588                                              Packet which is not of type \a PacketType.
589                                              \returns newly read packet reference. */
590         PacketType read();              ///< Alias for operator()
591     };
592
593     /** \brief Connector passively receiving packets
594
595         \tparam PacketType Type of packet to read. Defaults to senf::Packet
596
597         The %PassiveInput %connector template receives packets sent to it from a connected
598         %module. This class is completely implemented via it's base-class, GenericPassiveInput, 
599         the only difference is that read packets are returned as \a PacketType instead of generic
600         senf::Packet references.
601
602         \see GenericPassiveInput \n
603             senf::ppi::connector
604      */
605     template <class PacketType=Packet>
606     class PassiveInput : public GenericPassiveInput
607     {
608     public:
609         PacketType operator()();        ///< Read packet
610                                         /**< \throws std::bad_cast if the %connector receives a
611                                              Packet which is not of type \a PacketType.
612                                              \returns newly read packet reference. */
613         PacketType read();              ///< Alias for operator()
614     };
615
616     /** \brief Connector actively sending packets
617
618         \tparam PacketType Type of packet to send. Defaults to senf::Packet
619
620         The %ActiveOutput %connector template sends data actively to a connected %module. This 
621         class is completely implemented via it's base-class, GenericActiveOutput, the only
622         difference is that it only sends packets of type \a PacketType.
623
624         \see GenericActiveOutput \n
625             senf::ppi::connector
626      */
627     template <class PacketType=Packet>
628     class ActiveOutput : public GenericActiveOutput
629     {
630     public:
631         operator()(PacketType packet);  ///< Send out a packet
632         void write(PacketType packet);  ///< Alias for operator()
633     };
634
635     /** \brief Connector passively providing packets
636
637         \tparam PacketType Type of packet to send. Defaults to senf::Packet
638
639         The %PassiveOutput %connector template provides data passively to a connected %module 
640         whenever signaled. This class is completely implemented via it's base-class, 
641         GenericPassiveOutput, the only difference is that it only sends packets of type 
642         \a PacketType.
643
644         \see GenericPassiveOutput \n
645             senf::ppi::connector
646      */
647     template <class PacketType=Packet>
648     class PassiveOutput : public GenericPassiveOutput
649     {
650     public:
651         operator()(PacketType packet);  ///< Send out a packet
652         void write(PacketType packet);  ///< Alias for operator()
653     };
654
655 #endif
656
657 }}}
658
659 ///////////////////////////////hh.e////////////////////////////////////////
660 #include "Connectors.cci"
661 //#include "Connectors.ct"
662 #include "Connectors.cti"
663 #endif
664
665 \f
666 // Local Variables:
667 // mode: c++
668 // fill-column: 100
669 // c-file-style: "senf"
670 // indent-tabs-mode: nil
671 // ispell-local-dictionary: "american"
672 // compile-command: "scons -u test"
673 // comment-column: 40
674 // End: