PPI/Joins.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 Joins public header */
  25
  26 #ifndef HH_SENF_PPI_Joins_
  27 #define HH_SENF_PPI_Joins_ 1
  28
  29 // Custom includes
  30 #include <boost/ptr_container/ptr_vector.hpp>
  31 #include "predecl.hh"
  32 #include "Connectors.hh"
  33 #include "Module.hh"
  34
  35 //#include "Joins.mpp"
  36 ///////////////////////////////hh.p////////////////////////////////////////
  37
  38 namespace senf {
  39 namespace ppi {
  40
  41 #ifndef DOXYGEN
  42
  43     template <class Source>
  44     connector::GenericPassiveInput & connect(Source & source, module::PassiveJoin & target);
  45
  46     template <class Source>
  47     connector::GenericActiveInput & connect(Source & source, module::PriorityJoin & target,
  48                                             int priority = -1);
  49
  50 #endif
  51
  52 namespace module {
  53
  54     /** \brief Join multiple packet streams with passive inputs
  55
  56         The PassiveJoin will combine any number of packet streams. You may connect any number of
  57         ActiveOutput<>'s  to the PassiveJoin instance. The combined stream is then provided on the
  58         ActiveOutput<> \a output.
  59
  60         Since PassiveJoin allows any number of incoming packet streams, the input connectors are
  61         dynamically managed. A special senf::ppi::connect() overload is used to dynamically create
  62         the needed input connectors. This hides this extra functionality from the user.
  63         \code
  64         senf::ppi::module::PassiveJoin join;
  65
  66         ppi::connect(module1,join);             // Connect first module to join's input
  67         ppi::connect(module2.some_output,join); // Connect another module to join's input
  68         ppi::connect(join,module3);             // Forward combined stream to module3
  69         \endcode
  70
  71         \ingroup routing_modules
  72      */
  73     class PassiveJoin
  74         : public Module
  75     {
  76         SENF_PPI_MODULE(PassiveJoin);
  77     public:
  78         connector::ActiveOutput<> output;
  79
  80         PassiveJoin();
  81
  82     private:
  83         connector::PassiveInput<> & newInput();
  84
  85 #ifndef DOXYGEN
  86         // I didn't get template friend functions to work ...
  87     public:
  88 #endif
  89         template <class Source>
  90         connector::GenericPassiveInput & connect(Source & source);
  91
  92     private:
  93         void request(connector::GenericPassiveInput & input);
  94         void onThrottle();
  95         void onUnthrottle();
  96
  97         typedef boost::ptr_vector<connector::PassiveInput<> > Inputs;
  98         Inputs inputs_;
  99     };
 100
 101     /** \brief Join multiple packet streams with active inputs
 102
 103         The PriorityJoin will combine any number of packet streams. You may connect any number of
 104         PassiveInput<>'s  to the PassiveJoin instance. The combined stream is then provided on the
 105         PassiveOutput<> \a output.
 106
 107         When a packet request is received on Priorityjoin's \a output, The request will be serviced
 108         from the first unthrottled input. The order, in which connectors are connected to the
 109         PriorityJoin's input is important: The earlier connected peer has the higher priority and
 110         will be serviced first.
 111
 112         Since PriorityJoin allows any number of incoming packet streams, the input connectors are
 113         dynamically managed. A special senf::ppi::connect() overload is used to dynamically create
 114         the needed input connectors. This hides this extra functionality from the user.
 115         \code
 116         senf::ppi::module::PriorityJoin join;
 117
 118         ppi::connect(module1,join);             // Connect first module to join's input
 119         ppi::connect(module2.some_output,join); // Connect another module to join's input
 120         ppi::connect(join,module3);             // Forward combined stream to module3
 121         \endcode
 122         Here, \a module1 has higher priority than \a module2 which will only be queried if \a
 123         module1 is throttled.
 124
 125         \ingroup routing_modules
 126      */
 127     class PriorityJoin
 128         : public Module
 129     {
 130         SENF_PPI_MODULE(PriorityJoin);
 131     public:
 132         connector::PassiveOutput<> output;
 133
 134         PriorityJoin();
 135
 136     private:
 137         connector::ActiveInput<> & newInput(int priority);
 138
 139 #ifndef DOXYGEN
 140     public:
 141 #endif
 142         template <class Source>
 143         connector::GenericActiveInput & connect(Source & source, int prioricty);
 144
 145     private:
 146         void request();
 147         void onThrottle();
 148         void onUnthrottle();
 149
 150         typedef boost::ptr_vector<connector::ActiveInput<> > Inputs;
 151         Inputs inputs_;
 152     };
 153
 154 }}}
 155
 156 ///////////////////////////////hh.e////////////////////////////////////////
 157 #include "Joins.cci"
 158 //#include "Joins.ct"
 159 #include "Joins.cti"
 160 #endif
 161
 162 \f
 163 // Local Variables:
 164 // mode: c++
 165 // fill-column: 100
 166 // comment-column: 40
 167 // c-file-style: "senf"
 168 // indent-tabs-mode: nil
 169 // ispell-local-dictionary: "american"
 170 // compile-command: "scons -u test"
 171 // End: