PPI: Extend ppi::connect() / connector compatibility documentation

[senf.git] / PPI / Connectors.hh

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index a69c3d8..67d8c1b 100644 (file)
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -31,6 +31,7 @@
 #include <boost/utility.hpp>
 #include <boost/scoped_ptr.hpp>
 #include "../Utils/safe_bool.hh"
+#include "../Utils/Exception.hh"
 #include "../Packets/Packets.hh"
 #include "predecl.hh"
 #include "detail/Callback.hh"
@@ -46,9 +47,10 @@ 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
@@ -57,11 +59,12 @@ namespace connector {
         All passive connectors call some onRequest callback whenever I/O needs to be performed. All
         input modules 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.
@@ -99,6 +102,19 @@ 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") {} };
+
     /** \brief Connector base-class
 
         This connector provides access to the generic connector facilities. This includes the
@@ -119,6 +135,8 @@ namespace connector {
         void connect(Connector & target);
 
     private:
+        virtual std::type_info const & packetTypeID();
+
         void setModule(module::Module & module);
 
         Connector * peer_;
@@ -450,21 +468,23 @@ namespace connector {
 
 #   define TypedConnector_Input read
 #   define TypedConnector_Output write
-#   define TypedConnector(type, dir)                                                              \
+#   define TypedConnector(pType, dir)                                                             \
         template <class PacketType>                                                               \
-        class type ## dir                                                                         \
-            : public Generic ## type ## dir,                                                      \
-              private detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType>         \
+        class pType ## dir                                                                        \
+            : public Generic ## pType ## dir,                                                     \
+              private detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>        \
         {                                                                                         \
-            typedef detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType> mixin;    \
+            typedef detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType> mixin;   \
         public:                                                                                   \
             using mixin::operator();                                                              \
             using mixin::TypedConnector_ ## dir ;                                                 \
         private:                                                                                  \
-             friend class detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType>;    \
+            virtual std::type_info const & packetTypeID()                                         \
+                { return typeid(typename PacketType::type); }                                     \
+            friend class detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>;    \
         };                                                                                        \
         template <>                                                                               \
-        class type ## dir <Packet> : public Generic ## type ## dir                                \
+        class pType ## dir <Packet> : public Generic ## pType ## dir                              \
         {}
 
     TypedConnector( Passive, Input  );