senf/PPI/Queueing.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 Queueing public header */
  25
  26 #ifndef HH_SENF_PPI_Queueing_
  27 #define HH_SENF_PPI_Queueing_ 1
  28
  29 // Custom includes
  30 #include "predecl.hh"
  31
  32 //#include "Queueing.mpp"
  33 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  34
  35 namespace senf {
  36 namespace ppi {
  37
  38     /** \brief Queueing discipline base class
  39
  40         QueueingDescipline derived classes define the generation of throttling notifications. The
  41         QueueingDiscipline is called whenever the packets are entered or removed from the queue. The
  42         queueing discipline then determines the new throttling state of the queue.
  43
  44         \note The QueueingDiscipline will \e never drop packets explicitly. This is left to the
  45         operating system by sending throttling events. The PPI will never loose a packet internally
  46         (if not a module explicitly does so), however it may disable reception of new incoming
  47         packets which will then probably be dropped by the operating system.
  48
  49         \attention Notifications may be forwarded to the QueueingDiscipline implementation
  50             out-of-order: A dequeue event may be notified before the corresponding enqueue
  51             event (this happens to optimize away transient throttling state changes which would
  52             otherwise occur if a packet is entered into the queue and then removed from it in the
  53             same processing step).
  54      */
  55     class QueueingDiscipline
  56     {
  57     public:
  58         virtual ~QueueingDiscipline();
  59
  60         enum Event { ENQUEUE, DEQUEUE }; ///< Possible queueing events
  61         enum None_t { NONE };            ///< Type to disable the queueing discipline
  62
  63         virtual void update(connector::GenericPassiveInput & input, Event event) = 0;
  64                                         ///< Calculate new queueing state
  65                                         /**< Whenever the queue is manipulated, this member is
  66                                              called to calculate the new throttling state. The
  67                                              member must call \a input's \c throttle() or \c
  68                                              unthrottle() member to set the new throttling state.
  69
  70                                              \param[in] input Connector holding the queue
  71                                              \param[in] event Type of event triggering the update */
  72     };
  73
  74     /** \brief Simple queueing discipline with high and low threshold
  75
  76         The ThresholdQueueing QueueingDiscipline is a simple queueing discipline which throttles the
  77         input as soon the number of packets in the queue reaches the \a high threshold. The input
  78         will be unthrottled when the number of packets drops to the \a low threshold.
  79
  80         The default queueing discipline is ThresholdQueueing(1,0).
  81      */
  82     class ThresholdQueueing
  83         : public QueueingDiscipline
  84     {
  85     public:
  86         ThresholdQueueing(unsigned high, unsigned low);
  87
  88         virtual void update(connector::GenericPassiveInput & input, Event event);
  89
  90     private:
  91         unsigned high_;
  92         unsigned low_;
  93     };
  94
  95 }}
  96
  97 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  98 #include "Queueing.cci"
  99 //#include "Queueing.ct"
 100 //#include "Queueing.cti"
 101 #endif
 102
 103 \f
 104 // Local Variables:
 105 // mode: c++
 106 // fill-column: 100
 107 // c-file-style: "senf"
 108 // indent-tabs-mode: nil
 109 // ispell-local-dictionary: "american"
 110 // compile-command: "scons -u test"
 111 // comment-column: 40
 112 // End: