Enhancing Message Concept Documentation

deanberris · deanberris · commit 09cccd82246e · 2010-10-30T01:47:12.000+08:00
This documentation update discusses the difference between directives,
modifiers, and wrappers. It also enhances the definition of the Message
Concept in preparation for the possible simplification of the
basic_request and basic_response implementations to turn them into POD
types similar to the POD types used by the HTTP server implementation.
diff --git a/libs/network/doc/message.rst b/libs/network/doc/message.rst
@@ -43,10 +43,16 @@ properties of messages.
 :m,n: An instance of **M**.
 :S: A string type.
 :s,k,v: An instance of **S**.
+:O: The source type.
+:D: The destination type.
+:B: The body type.
+:T: The Tag type.
 
 +----------------------------+----------------------+-----------------------------------------+
 | Construct                  | Result               | Description                             |
 +============================+======================+=========================================+
+| ``typename M::tag``        | T                    | The nested tag type.                    |
++----------------------------+----------------------+-----------------------------------------+
 | ``M()``                    | Instance of M        | Default constructible.                  |
 +----------------------------+----------------------+-----------------------------------------+
 | ``M(m)``                   | Instance of M        | Copy constructible.                     |
@@ -55,33 +61,34 @@ properties of messages.
 +----------------------------+----------------------+-----------------------------------------+
 | ``swap(m, n);``            | ``void``             | Swappable.                              |
 +----------------------------+----------------------+-----------------------------------------+
-| ``source(m);``             | unspecified          | Retrieve the source of ``m``.           |
+| ``source(m);``             | Convertible to O     | Retrieve the source of ``m``.           |
 +----------------------------+----------------------+-----------------------------------------+
-| ``destination(m);``        | unspecified          | Retrieve the destination of ``m``.      |
+| ``destination(m);``        | Convertible to D     | Retrieve the destination of ``m``.      |
 +----------------------------+----------------------+-----------------------------------------+
-| ``headers(m);``            | unspecified          | Get the range of headers of ``m``. The  |
-|                            |                      | result should be convertible to ``H``   |
+| ``headers(m);``            | Convertible to H     | Retrieve the headers of ``m``.          |
 +----------------------------+----------------------+-----------------------------------------+
-| ``body(m);``               | unspecified          | Retrieve the body of ``m``.             |
+| ``body(m);``               | Convertible to B     | Retrieve the body of ``m``.             |
 +----------------------------+----------------------+-----------------------------------------+
 | ``m << source(s);``        | ``M &``              | Set the source of ``m``.                |
 +----------------------------+----------------------+-----------------------------------------+
-| ``source(m,s);``           | ``M &``              | Set the source of ``m``.                |
-+----------------------------+----------------------+-----------------------------------------+
 | ``m << destination(s);``   | ``M &``              | Set the destination of ``m``.           |
 +----------------------------+----------------------+-----------------------------------------+
-| ``destination(m,s);``      | ``M &``              | Set the destination of ``m``.           |
-+----------------------------+----------------------+-----------------------------------------+
 | ``m << header(k, v);``     | ``M &``              | Add a header to ``m``.                  |
 +----------------------------+----------------------+-----------------------------------------+
-| ``add_header(m, k, v);``   | ``M &``              | Add a header to ``m``.                  |
-+----------------------------+----------------------+-----------------------------------------+
 | ``m << remove_header(k);`` | ``M &``              | Remove a header from ``m``.             |
 +----------------------------+----------------------+-----------------------------------------+
-| ``remove_header(m, k);``   | ``M &``              | Remove a header from ``m``.             |
-+----------------------------+----------------------+-----------------------------------------+
 | ``m << body(s);``          | ``M &``              | Set the body of ``m``.                  |
 +----------------------------+----------------------+-----------------------------------------+
+| ``source(m,s);``           | ``void``             | Set the source of ``m``.                |
++----------------------------+----------------------+-----------------------------------------+
+| ``destination(m,s);``      | ``void``             | Set the destination of ``m``.           |
++----------------------------+----------------------+-----------------------------------------+
+| ``add_header(m, k, v);``   | ``void``             | Add a header to ``m``.                  |
++----------------------------+----------------------+-----------------------------------------+
+| ``remove_header(m, k);``   | ``void``             | Remove a header from ``m``.             |
++----------------------------+----------------------+-----------------------------------------+
+| ``clear_headers(m);``      | ``void``             | Clear the headers of ``m``.             |
++----------------------------+----------------------+-----------------------------------------+
 | ``body(m,s);``             | ``M &``              | Set the body of ``m``.                  |
 +----------------------------+----------------------+-----------------------------------------+
 
@@ -93,6 +100,105 @@ Concept, a message can be implemented as a POD type and have all
 manipulations performed in the directive implementations, as well as
 value transformations done in the accessors.
 
+Directives, Modifiers, and Wrappers
+```````````````````````````````````
+
+In the Message Concept definition there are three basic constructs that follow a
+certain pattern. These patterns are Directives_, Modifiers_, and Wrappers_.
+
+Directives
+~~~~~~~~~~
+
+A directive is a function object that is applied to a Message. Directives
+encapsulate a set of operations that apply to messages. The general requirement
+for a Directive is that it should apply these operations on a message.
+
+A directive may dispatch on the type of the message passed to it at the point of
+the function call. Typically, directives are generated using a factory function
+that returns the correct directive type.
+
+For a given directive ``foo_directive`` a generator function called ``foo`` is
+typically implemented:
+
+.. code-block:: c++
+
+    struct foo_directive {
+        template <class Message>
+        Message & operator()(Message & m) const {
+            // do something to m
+            return m;
+        }
+    };
+
+    foo_directive const foo() {
+        return foo_directive();
+    }
+
+    // to apply a directive, we use the << operator
+    message m;
+    m << foo();
+
+Modifiers
+~~~~~~~~~
+
+A modifier is generally defined as a free function that takes a reference to a
+non-const lvalue message as the first parameter, and any number of parameters.
+In the concept definition of the Message Concept, a modifier follows the form:
+
+.. code-block:: c++
+
+    modifier(message, ...)
+
+Modifiers are meant to imply modifications on a message, which also allows for
+easier dispatch based on Argument Dependent Lookup (ADL_) on the type of the
+message. Note that Directives_ can be implemented in terms of Modifiers and 
+vice versa, although that is not required nor specified.
+
+.. _ADL: http://en.wikipedia.org/wiki/Argument-dependent_name_lookup
+
+Wrappers
+~~~~~~~~
+
+A Wrapper is basically an implementation detail that ensures that a given
+message, when wrapped, can be converted to the associated part of the message. A
+wrapper has a type that encapsulates the conversion logic from a message to a
+given type.
+
+An example of a Wrapper would be ``source_wrapper`` which would be returned by a
+call to the wrapper generator function ``source``. An example implementation of
+the ``source_wrapper`` would look like:
+
+.. code-block:: c++
+
+    template <class Tag, template <class> class Message>
+    struct source_wrapper {
+        Message<Tag> const & m;
+        explicit source_wrapper(Message<Tag> const & m)
+        : m(m) {}
+        typedef typename source<Tag>::type source_type;
+        operator source_type const & () {
+            return m.source;
+        }
+        operator source_type const () {
+            return m.source;
+        }
+        operator source_type () {
+            return m.source;
+        }
+    };
+
+    template <class Tag, template <class> class Message>
+    source_wrapper<Tag, Message> const
+    source(Message<Tag> const & message) {
+        return source_wrapper<Tag, Message>(message);
+    }
+
+This pattern is similar to an adapter, but the specific notion of wrapping a
+data type (in this case, an object of a type that models the Message Concept)
+using an intermediary wrapper is what is pertained to by the Wrapper pattern.
+In this case, the Wrapper is ``source_wrapper`` while ``source`` is merely a
+wrapper generator function.
+
 ``basic_message``
 `````````````````
 
