Completed first stage of PPI API specification

[senf.git] / PPI / Connectors.hh

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index 907d5a9..1b299e2 100644 (file)
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -49,6 +49,9 @@
 namespace senf {
 namespace ppi {
 
+    ///@{
+    ///\addtogroup connectors
+
     /** \brief Connector baseclass
 
         This connector provides access to the generic connector facilities. This includes the
@@ -83,8 +86,6 @@ namespace ppi {
             notifications
 
         The accumulative throttling state is generated by combining all sub-states.
-
-        \ingroup connectors
      */
     class PassiveConnector 
         : public virtual Connector
@@ -130,8 +131,6 @@ namespace ppi {
         Active connectors do not handle any throttling state, they just receive the
         notifications. These notifications should then either be processed by the module or be
         forwarded to other connectors.
-
-        \ingroup connectors
      */
     class ActiveConnector 
         : public virtual Connector
@@ -176,7 +175,18 @@ namespace ppi {
         packets in batches or generating multiple output packets from a single input packet. The
         queues have the potential to greatly simplify the module implementations.
 
-        \ingroup connectors
+        \implementation Which container to use?
+            \li list has good insertion and deletion properties on both ends but it costs a dynamic
+                memory allocation for every insertion. A very good property is, that iterators stay
+                valid across insertions/deletions
+            \li vector is fast and has good amortized dynamic allocation properties. However, it is
+                quite unusable as a queue
+            \li deque has comparable dynamic allocation properties as vector but also has good
+                insertion/removal properties on both ends.
+
+            So probably we will use a deque. I'd like a container which keeps iterators intact on
+            isertion/deletion but I believe that list is just to expensive since every packet will
+            be added to the queue before it can be processed.
      */
     class InputConnector 
         : public virtual Connector
@@ -232,8 +242,6 @@ namespace ppi {
         An output connector sends out packets. It may be either an ActiveConnector or a
         PassiveConnector. An output connector does \e not have an built-in queueing, it relies on
         the queueing of the connected input.
-
-        \ingroup connectors
      */
     class OutputConnector 
         : public virtual Connector
@@ -251,7 +259,13 @@ namespace ppi {
 
     /** \brief Combination of PassiveConnector and InputConnector
 
-        \ingroup connectors
+        In addition to the native and the forwarded throttling state, the PassiveInput manages a
+        queue throttling state. This state is automatically managed by a queueing discipline. The
+        standard queueing discipline is ThresholdQueueing, which throttles the connection whenever
+        the queue length reaches the high threshold and unthrottles the connection when the queue
+        reaches the low threshold. The default queueing discpiline is
+        <tt>ThresholdQueueing(1,0)</tt> which will throttle the input whenever the queue is
+        non-empty.
      */
     class PassiveInput 
         : public PassiveConnector, public InputConnector
@@ -259,13 +273,15 @@ namespace ppi {
     public:
         ActiveOutput & peer();
 
-        template <class QDisc>
-        QDisc const & qdisc(QDisc const & disc);
+        template <class QueueingDiscipline>
+        void qdisc(QueueingDiscipline const & disc); ///< Change the queueing discipline
+                                        /**< The queueing discipline is a class which provides the
+                                             QueueingDiscipline interface.
+                                             
+                                             \param[in] disc New queueing discipline */
     };
 
     /** \brief Combination of PassiveConnector and OutputConnector
-
-        \ingroup connectors
      */
     class PassiveOutput
         : public PassiveConnector, public OutputConnector
@@ -275,21 +291,17 @@ namespace ppi {
     };
 
     /** \brief Combination of ActiveConnector and InputConnector
-
-        \ingroup connectors
      */
     class ActiveInput
         : public ActiveConnector, public InputConnector
     {
     public:
-        void request();                 ///< request more packets without dequeing any packet
-
         PassiveOutput & peer();
+
+        void request();                 ///< request more packets without dequeing any packet
     };
 
     /** \brief Combination of ActiveConnector and OutputConnector
-
-        \ingroup connectors
      */
     class ActiveOutput
         : public ActiveConnector, public OutputConnector
@@ -298,6 +310,8 @@ namespace ppi {
         ActiveInput & peer();
     };
 
+    ///@}
+
 }}
 
 ///////////////////////////////hh.e////////////////////////////////////////