Utils/Termlib: Extend the completion API

[senf.git] / PPI / Queueing.hh

diff --git a/PPI/Queueing.hh b/PPI/Queueing.hh
index 7b7421e..5ed6a9f 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
@@ -21,8 +23,8 @@
 /** \file
     \brief Queueing public header */
 
-#ifndef HH_Queueing_
-#define HH_Queueing_ 1
+#ifndef HH_SENF_PPI_Queueing_
+#define HH_SENF_PPI_Queueing_ 1
 
 // Custom includes
 #include "predecl.hh"
@@ -43,6 +45,12 @@ 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
     {
@@ -50,22 +58,43 @@ namespace ppi {
         virtual ~QueueingDiscipline();
 
         enum Event { ENQUEUE, DEQUEUE }; ///< Possible queueing events
-        enum State { THROTTLED, UNTHROTTLED }; ///< Possible queueing states
         
-        virtual State update(connector::PassiveInput & input, Event event) = 0;
+        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 update
-                                             \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