Socket: Add missing InetSocketProtocol baseclass to relevant socket protocols
[senf.git] / PPI / Connectors.hh
index 60b1f71..0874551 100644 (file)
@@ -47,22 +47,24 @@ namespace connector {
     /** \namespace senf::ppi::connector
         \brief Connector classes
 
-        A connector has two independent properties
-        - it may be \e active or \e passive
-        - it may be an \e input or an \e output
+        A connector has three independent properties
+        \li it may be \e active or \e passive
+        \li it may be an \e input or an \e output
+        \li it has an (optional) packet type
 
         \e Active connectors are activated from within the module, \e passive connectors are
-        signaled by the external framework. \e Input modules receive packets, \e output modules send
-        packets.
+        signaled by the external framework. \e Input connectors receive packets, \e output
+        connectors send packets.
 
         All passive connectors call some onRequest callback whenever I/O needs to be performed. All
-        input modules possess a packet queue.
+        input connectors possess a packet queue.
 
-        We therefore have 4 connector types:
-        - senf::ppi::connector::ActiveInput
-        - senf::ppi::connector::ActiveOutput
-        - senf::ppi::connector::PassiveInput
-        - senf::ppi::connector::PassiveOutput.
+        We therefore have 4 connector types each of which is parameterized by the type of packet
+        traversing the connector:
+        \li senf::ppi::connector::ActiveInput
+        \li senf::ppi::connector::ActiveOutput 
+        \li senf::ppi::connector::PassiveInput 
+        \li senf::ppi::connector::PassiveOutput.
 
         Connectors are declared as module data members and are then externally connected to other
         modules.
@@ -88,7 +90,7 @@ namespace connector {
         private:
             void onRequest() {
                 // 'input()' will return a senf::EthernetPacket packet handle
-                try { output( input().find<IpPacket>() ); }
+                try { output( input().find<senf::IpPacket>() ); }
                 catch (senf::InvalidPacketChainException & ex) { ; }
             }
         };
@@ -100,6 +102,16 @@ namespace connector {
             \ref ppi_connectors
      */
 
+    /** \brief Incompatible connectors connected
+
+        This exception is thrown, when two incompatible connectors are connected. This happens if
+        both connectors of a senf::ppi::connect() statement declare a packet type (the connector
+        template argument) but they don't declare the same packet type.
+
+        You need to ensure, that both connectors use the same packet type.
+
+        \see senf::ppi::connect()
+     */
     struct IncompatibleConnectorsException : public senf::Exception
     { IncompatibleConnectorsException() : senf::Exception("Incompatible connectors") {} };
 
@@ -116,16 +128,20 @@ namespace connector {
         Connector & peer() const;       ///< Get peer connected to this connector
         module::Module & module() const; ///< Get this connectors containing module
 
+        bool connected() const;         ///< \c true, if connector connected, \c false otherwise
+
     protected:
         Connector();
         virtual ~Connector();
 
         void connect(Connector & target);
-
+        
     private:
         virtual std::type_info const & packetTypeID();
 
         void setModule(module::Module & module);
+        void init();        
+        virtual void v_init() = 0;        
 
         Connector * peer_;
         module::Module * module_;
@@ -181,6 +197,8 @@ namespace connector {
         void emit();
 
     private:
+        virtual void v_init();
+
         // Called by the routing to change the remote throttling state
         void notifyThrottle();          ///< Forward a throttle notification to this connector
         void notifyUnthrottle();        ///< Forward an unthrottle notification to this connector
@@ -256,6 +274,8 @@ namespace connector {
         ActiveConnector();
 
     private:
+        virtual void v_init();
+
         // called by the peer() to forward throttling notifications
         void notifyThrottle();
         void notifyUnthrottle();
@@ -269,6 +289,8 @@ namespace connector {
         typedef std::vector<ForwardingRoute*> NotifyRoutes;
         NotifyRoutes notifyRoutes_;
 
+        bool throttled_;        
+
         friend class senf::ppi::ForwardingRoute;
         friend class PassiveConnector;
     };
@@ -490,9 +512,10 @@ namespace connector {
         
         \tparam PacketType Type of packet to read. Defaults to senf::Packet
 
-        The ActiveInput connector template reads data actively from a connected module. This class
-        is completely implemented via it's base-class, GenericActiveInput, the only difference is
-        that read packets are returned as \a PacketType instead of generic senf::Packet references.
+        The %ActiveInput %connector template reads data actively from a connected %module. This
+        class is completely implemented via it's base-class, GenericActiveInput, the only 
+        difference is that read packets are returned as \a PacketType instead of generic 
+        senf::Packet references.
 
         \see GenericActiveInput \n
             senf::ppi::connector
@@ -502,7 +525,7 @@ namespace connector {
     {
     public:
         PacketType operator()();        ///< Read packet
-                                        /**< \throws std::bad_cast, if the connector receives a
+                                        /**< \throws std::bad_cast, if the %connector receives a
                                              Packet which is not of type \a PacketType.
                                              \returns newly read packet reference. */
         PacketType read();              ///< Alias for operator()
@@ -512,9 +535,9 @@ namespace connector {
 
         \tparam PacketType Type of packet to read. Defaults to senf::Packet
 
-        The PassiveInput connector template receives packets sent to it from a connected
-        module. This class is completely implemented via it's base-class, GenericPassiveInput, the
-        only difference is that read packets are returned as \a PacketType instead of generic
+        The %PassiveInput %connector template receives packets sent to it from a connected
+        %module. This class is completely implemented via it's base-class, GenericPassiveInput, 
+        the only difference is that read packets are returned as \a PacketType instead of generic
         senf::Packet references.
 
         \see GenericPassiveInput \n
@@ -525,7 +548,7 @@ namespace connector {
     {
     public:
         PacketType operator()();        ///< Read packet
-                                        /**< \throws std::bad_cast, if the connector receives a
+                                        /**< \throws std::bad_cast, if the %connector receives a
                                              Packet which is not of type \a PacketType.
                                              \returns newly read packet reference. */
         PacketType read();              ///< Alias for operator()
@@ -535,9 +558,9 @@ namespace connector {
 
         \tparam PacketType Type of packet to send. Defaults to senf::Packet
 
-        The ActiveOutput connector template sends data actively to a connected module. This class is
-        completely implemented via it's base-class, GenericActiveOutput, the only difference is that
-        it only sends packets of type \a PacketType.
+        The %ActiveOutput %connector template sends data actively to a connected %module. This 
+        class is completely implemented via it's base-class, GenericActiveOutput, the only
+        difference is that it only sends packets of type \a PacketType.
 
         \see GenericActiveOutput \n
             senf::ppi::connector
@@ -547,16 +570,17 @@ namespace connector {
     {
     public:
         operator()(PacketType packet);  ///< Send out a packet
-        write(PacketType packet);       ///< Alias for operator()
+        void write(PacketType packet);  ///< Alias for operator()
     };
 
     /** \brief Connector passively providing packets
 
         \tparam PacketType Type of packet to send. Defaults to senf::Packet
 
-        The PassiveOutput connector template provides data passively to a connected module whenever
-        signaled. This class is completely implemented via it's base-class, GenericPassiveOutput, the
-        only difference is that it only sends packets of type \a PacketType.
+        The %PassiveOutput %connector template provides data passively to a connected %module 
+        whenever signaled. This class is completely implemented via it's base-class, 
+        GenericPassiveOutput, the only difference is that it only sends packets of type 
+        \a PacketType.
 
         \see GenericPassiveOutput \n
             senf::ppi::connector
@@ -566,7 +590,7 @@ namespace connector {
     {
     public:
         operator()(PacketType packet);  ///< Send out a packet
-        write(PacketType packet);       ///< Alias for operator()
+        void write(PacketType packet);  ///< Alias for operator()
     };
 
 #endif