removed some useless spaces; not very important, I know :)

[senf.git] / PPI / Queueing.hh

diff --git a/PPI/Queueing.hh b/PPI/Queueing.hh
index 7410318..16cecb4 100644 (file)
--- a/PPI/Queueing.hh
+++ b/PPI/Queueing.hh
@@ -1,6 +1,8 @@
-// Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// $Id$
+//
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -25,6 +27,7 @@
 #define HH_Queueing_ 1
 
 // Custom includes
+#include "predecl.hh"
 
 //#include "Queueing.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
@@ -42,26 +45,56 @@ namespace ppi {
         operating system by sending throttling events. The PPI will never loose a packet internally
         (if not a module explicitly does so), however it may disable reception of new incoming
         packets which will then probably be dropped by the operating system.
+
+        \attention Notifications may be forwarded to the QueueingDiscipline implementation
+            out-of-order: A dequeue event may be notified before the corresponding enqueue
+            event (this happens to optimize away transient throttling state changes which would
+            otherwise occur if a packet is entered into the queue and then removed from it in the
+            same processing step).
      */
     class QueueingDiscipline
     {
     public:
-        enum Event { ENQUEUE, DEQUEUE }; ///< Possible queueing events
-        enum State { THROTTLED, UNTHROTTLED }; ///< Possible queueing states
+        virtual ~QueueingDiscipline();
 
-        State update(PassiveInput & input, Event event) = 0; ///< Calculate new queueing state
+        enum Event { ENQUEUE, DEQUEUE }; ///< Possible queueing events
+        
+        virtual void update(connector::GenericPassiveInput & input, Event event) = 0;
+                                        ///< Calculate new queueing state
                                         /**< Whenever the queue is manipulated, this member is
-                                             called to calculate the new throttling state.
+                                             called to calculate the new throttling state. The
+                                             member must call \a input's \c throttle() or \c
+                                             unthrottle() member to set the new throttling state.
                                              
                                              \param[in] input Connector holding the queue
-                                             \param[in] event Type of event triggering the upate
-                                             \returns new throttling state */
+                                             \param[in] event Type of event triggering the update */
+    };
+
+    /** \brief Simple queueing discipline with high and low threshold
+
+        The ThresholdQueueing QueueingDiscipline is a simple queueing discipline which throttles the
+        input as soon the number of packets in the queue reaches the \a high threshold. The input
+        will be unthrottled when the number of packets drops to the \a low threshold. 
+
+        The default queueing discipline is ThresholdQueueing(1,0).
+     */
+    class ThresholdQueueing
+        : public QueueingDiscipline
+    {
+    public:
+        ThresholdQueueing(unsigned high, unsigned low);
+
+        virtual void update(connector::GenericPassiveInput & input, Event event);
+
+    private:
+        unsigned high_;
+        unsigned low_;
     };
 
 }}
 
 ///////////////////////////////hh.e////////////////////////////////////////
-//#include "Queueing.cci"
+#include "Queueing.cci"
 //#include "Queueing.ct"
 //#include "Queueing.cti"
 #endif
@@ -74,4 +107,5 @@ namespace ppi {
 // indent-tabs-mode: nil
 // ispell-local-dictionary: "american"
 // compile-command: "scons -u test"
+// comment-column: 40
 // End: