X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=PPI%2FConnectors.hh;h=78b7023f1d6cacef07bc159c710af7c0de005019;hb=a1fdb7bb122f0b05be809a922d4b7ef5e125fa67;hp=e5ea9c91cf064241613ee072a6a963e0d7edf69d;hpb=c7ddbbb0bc014bdfe6daef91e2d1c512d77e9fff;p=senf.git

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index e5ea9c9..78b7023 100644
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -23,8 +23,8 @@
 /** \file
     \brief Connectors public header */
 
-#ifndef HH_Connectors_
-#define HH_Connectors_ 1
+#ifndef HH_SENF_PPI_Connectors_
+#define HH_SENF_PPI_Connectors_ 1
 
 // Custom includes
 #include <deque>
@@ -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
@@ -350,7 +386,7 @@ namespace connector {
         InputConnector();
 
     private:
-        void enqueue(Packet p);
+        void enqueue(Packet const & p);
 
         virtual void v_requestEvent();
         virtual void v_enqueueEvent();
@@ -371,9 +407,9 @@ namespace connector {
         : public virtual Connector
     {
     public:
-        void operator()(Packet p);      ///< Send out a packet
+        void operator()(Packet const & p);      ///< Send out a packet
 
-        void write(Packet p);           ///< Alias for operator()(Packet p)
+        void write(Packet const & p);           ///< Alias for operator()(Packet p)
 
         InputConnector & peer() const;
 
@@ -526,7 +562,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()
@@ -549,7 +585,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()