Socket: Fix handle.state() on invalid handles

[senf.git] / PPI / Connectors.hh

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index 4f18a78..e6b8c07 100644 (file)
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -97,6 +97,42 @@ namespace connector {
         };
         \endcode
 
+
+        \section ppi_jacks Jacks
+
+        A Jack is a packet type aware and possibly packet type converting reference to an arbitrary
+        connector of the same type. Jacks are used in groups to indirectly declare the input's and
+        output's
+
+        \code
+        class MyGroup
+        {
+        private:
+            senf::ppi::module::PassiveQueue queue;
+            senf::ppi::module::RateAnalyzer analyzer;
+
+        public:
+            senf::ppi::connector::ActiveInputJack<senf::EthernetPacket> input;
+            senf::ppi::connector::ActiveOutputJack<senf::EthernetPacket> output;
+
+            MyGroup() 
+                : queue (), analyzer (), input (queue.input), output (analyzer.output)
+            {
+                senf::ppi::connect(queue, analyzer);
+            }
+        };
+        \endcode
+
+        The jacks are initialized by passing an arbitrary compatible connector to the jack
+        constructor. A connector is compatible, if
+        \li It has the same input/output active/passive specification
+        \li Either the Jack or the Connector are generic (senf::Packet) or Jack and Connector have
+            the same packet type
+
+        Jacks can be used wherever connectors may be used. Jacks may be defined anywhere, not only
+        in modules. It is however important to ensure that the lifetime of the jack does not exceed
+        the lifetime of the referenced connector.
+
         \see
             senf::ppi::module::Module \n
             senf::ppi::connect() \n
@@ -125,6 +161,8 @@ namespace connector {
     class Connector
         : ModuleManager::Initializable, boost::noncopyable
     {
+        SENF_LOG_CLASS_AREA();
+        SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
     public:
         Connector & peer() const;       ///< Get peer connected to this connector
         module::Module & module() const; ///< Get this connectors containing module
@@ -133,11 +171,19 @@ namespace connector {
 
         void disconnect();              ///< Disconnect connector from peer
 
+        enum TraceState { NO_TRACING, TRACE_IDS, TRACE_CONTENTS };
+
+        static void tracing(TraceState state);
+        static TraceState tracing();
+
     protected:
         Connector();
         virtual ~Connector();
 
         void connect(Connector & target);
+
+        void trace(Packet const & p, char const * label);
+        void throttleTrace(char const * label, char const * type);
         
     private:
         virtual std::type_info const & packetTypeID();
@@ -147,6 +193,8 @@ namespace connector {
         Connector * peer_;
         module::Module * module_;
 
+        static TraceState traceState_;
+
         friend class module::Module;
     };
 
@@ -200,11 +248,11 @@ namespace connector {
     private:
         virtual void v_init();
 
-        // Called by the routing to change the remote throttling state
+        // Called by the routing to change the throttling state from forwarding routes
         void notifyThrottle();          ///< Forward a throttle notification to this connector
         void notifyUnthrottle();        ///< Forward an unthrottle notification to this connector
 
-        // Internal members to emit throttling notifications
+        // Internal members to emit throttling notifications to the connected peer
         void emitThrottle();
         void emitUnthrottle();