PPI: Add optional template arg for packet type to connectors

[senf.git] / PPI / Setup.hh

diff --git a/PPI/Setup.hh b/PPI/Setup.hh
index 57215b1..e8da601 100644 (file)
--- a/PPI/Setup.hh
+++ b/PPI/Setup.hh
@@ -1,8 +1,8 @@
 // $Id$
 //
 // Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// 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
@@ -27,6 +27,8 @@
 #define HH_Setup_ 1
 
 // Custom includes
+#include <boost/type_traits.hpp>
+#include <boost/utility/enable_if.hpp>
 #include "predecl.hh"
 
 //#include "Setup.mpp"
@@ -35,34 +37,65 @@
 namespace senf {
 namespace ppi {
 
+    /** \brief Connect modules
+
+        senf::ppi::connect() establishes a connection between two modules or, to be more precise,
+        between two connectors. It will connect any input to any output connector as long as one is
+        active and the other passive.
+
+        If a module has an output connector called \c output, the module may be directly specified
+        as \a source argument. In the same way, if a module has an input connector called \c input,
+        the module may be given directly as \a target argument. This simplifies the most common case
+        of a module with one input and one output connector.
+        
+        \see \ref ppi_connections
+     */
+    void connect(connector::GenericActiveOutput & source, connector::GenericPassiveInput & target);
+
+    /** \brief Connect modules
+        \see connect() */
+    void connect(connector::GenericPassiveOutput & source, connector::GenericActiveInput & target);
+
 #ifndef DOXYGEN    
 
-    void connect(connector::ActiveOutput & source, connector::PassiveInput & target);
-    void connect(connector::PassiveOutput & source, connector::ActiveInput & target);
-    
-    template <class M, class C>
-    void connect(M & source, C & target,
-                 typename boost::enable_if< boost::is_base_of<module::Module, M> >::type * = 0,
+    template <class T, class C>
+    void connect(T & source, C & target,
+                 typename boost::disable_if< boost::is_base_of<connector::Connector, T> >::type * = 0,
                  typename boost::enable_if< boost::is_base_of<connector::Connector, C> >::type * = 0);
 
-    template <class C, class M>
-    void connect(C & source, M & target,
+    template <class C, class T>
+    void connect(C & source, T & target,
                  typename boost::enable_if< boost::is_base_of<connector::Connector, C> >::type * = 0,
-                 typename boost::enable_if< boost::is_base_of<module::Module, M> >::type * = 0);
+                 typename boost::disable_if< boost::is_base_of<connector::Connector,T> >::type * = 0);
 
-    template <class M1, class M2>
-    void connect(M1 & source, M2 & target,
-                 typename boost::enable_if< boost::is_base_of<module::Module, M1> >::type * = 0,
-                 typename boost::enable_if< boost::is_base_of<module::Module, M2> >::type * = 0);
+    template <class T1, class T2>
+    void connect(T1 & source, T2 & target,
+                 typename boost::disable_if< boost::is_base_of<connector::Connector, T1> >::type * = 0,
+                 typename boost::disable_if< boost::is_base_of<connector::Connector, T2> >::type * = 0);
 
-#else
+#endif
+    
+    /** \brief Start the network
 
-    template <class Source, class Target>
-    void connect(Source & source, Target & target);
+        Calling senf::ppi::run() will start processing the network. The main event loop is managed
+        by the Scheduler. Before starting the Scheduler main loop, all Module init() members are
+        called.
 
-#endif
+        senf::ppi::run() will return when no more work is to be done, that is when no events are
+        enabled (Since the events are enabled and disabled by the throttle notifications which
+        depend among other things on the packet queues, this is the same as checking for packets in
+        any queue). It is Ok to call senf::ppi::run() multiple times during the program lifetime.
 
+        \see \ref ppi_run
+     */
     void run();
+
+    /** \brief Manually initialize the network
+        
+        For debugging purposes, it is sometimes simpler to not use senf::ppi::run() but instead
+        drive the network via explicit calls using the debug modules. However, it is still necessary
+        to initialize the network. This operation is performed by senf::ppi::init().
+     */
     void init();
 
 }}