senf/PPI/Queueing.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief Queueing public header */
  30
  31 #ifndef HH_SENF_PPI_Queueing_
  32 #define HH_SENF_PPI_Queueing_ 1
  33
  34 // Custom includes
  35 #include "predecl.hh"
  36
  37 //#include "Queueing.mpp"
  38 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  39
  40 namespace senf {
  41 namespace ppi {
  42
  43     /** \brief Queueing discipline base class
  44
  45         QueueingDescipline derived classes define the generation of throttling notifications. The
  46         QueueingDiscipline is called whenever the packets are entered or removed from the queue. The
  47         queueing discipline then determines the new throttling state of the queue.
  48
  49         \note The QueueingDiscipline will \e never drop packets explicitly. This is left to the
  50         operating system by sending throttling events. The PPI will never loose a packet internally
  51         (if not a module explicitly does so), however it may disable reception of new incoming
  52         packets which will then probably be dropped by the operating system.
  53
  54         \attention Notifications may be forwarded to the QueueingDiscipline implementation
  55             out-of-order: A dequeue event may be notified before the corresponding enqueue
  56             event (this happens to optimize away transient throttling state changes which would
  57             otherwise occur if a packet is entered into the queue and then removed from it in the
  58             same processing step).
  59      */
  60     class QueueingDiscipline
  61     {
  62     public:
  63         virtual ~QueueingDiscipline();
  64
  65         enum Event { ENQUEUE, DEQUEUE }; ///< Possible queueing events
  66         enum None_t { NONE };            ///< Type to disable the queueing discipline
  67
  68         virtual void update(connector::GenericPassiveInput & input, Event event) = 0;
  69                                         ///< Calculate new queueing state
  70                                         /**< Whenever the queue is manipulated, this member is
  71                                              called to calculate the new throttling state. The
  72                                              member must call \a input's \c throttle() or \c
  73                                              unthrottle() member to set the new throttling state.
  74
  75                                              \param[in] input Connector holding the queue
  76                                              \param[in] event Type of event triggering the update */
  77     };
  78
  79     /** \brief Simple queueing discipline with high and low threshold
  80
  81         The ThresholdQueueing QueueingDiscipline is a simple queueing discipline which throttles the
  82         input as soon the number of packets in the queue reaches the \a high threshold. The input
  83         will be unthrottled when the number of packets drops to the \a low threshold.
  84
  85         The default queueing discipline is ThresholdQueueing(1,0).
  86      */
  87     class ThresholdQueueing
  88         : public QueueingDiscipline
  89     {
  90     public:
  91         ThresholdQueueing(unsigned high, unsigned low);
  92
  93         virtual void update(connector::GenericPassiveInput & input, Event event);
  94
  95     private:
  96         unsigned high_;
  97         unsigned low_;
  98     };
  99
 100 }}
 101
 102 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 103 #include "Queueing.cci"
 104 //#include "Queueing.ct"
 105 //#include "Queueing.cti"
 106 #endif
 107
 108 \f
 109 // Local Variables:
 110 // mode: c++
 111 // fill-column: 100
 112 // c-file-style: "senf"
 113 // indent-tabs-mode: nil
 114 // ispell-local-dictionary: "american"
 115 // compile-command: "scons -u test"
 116 // comment-column: 40
 117 // End: