[Boost-commit] svn:boost r80622 - in sandbox/type_erasure/libs/type_erasure: doc example

Subject: [Boost-commit] svn:boost r80622 - in sandbox/type_erasure/libs/type_erasure: doc example
From: steven_at_[hidden]
Date: 2012-09-21 16:50:45

Author: steven_watanabe
Date: 2012-09-21 16:50:44 EDT (Fri, 21 Sep 2012)
New Revision: 80622
URL: http://svn.boost.org/trac/boost/changeset/80622

Log:
Try to improve documentation based on the review comments.
Text files modified: 
   sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk |   198 ++++++++++++++++++++++++--------------- 
   sandbox/type_erasure/libs/type_erasure/example/basic.cpp    |    69 +++++++++++++                           
   sandbox/type_erasure/libs/type_erasure/example/custom.cpp   |    20 ++-                                     
   sandbox/type_erasure/libs/type_erasure/example/overload.cpp |    11 +                                       
   4 files changed, 203 insertions(+), 95 deletions(-)

Modified: sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk	(original)
+++ sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk	2012-09-21 16:50:44 EDT (Fri, 21 Sep 2012)
@@ -65,31 +65,70 @@
 [def __random_access_iterator [classref boost::type_erasure::random_access_iterator random_access_iterator]]
 [def __same_type [classref boost::type_erasure::same_type same_type]]
 
+[def __BOOST_TYPE_ERASURE_MEMBER [macroref BOOST_TYPE_ERASURE_MEMBER]]
+[def __BOOST_TYPE_ERASURE_FREE [macroref BOOST_TYPE_ERASURE_FREE]]
 
 [section:introduction Introduction]
 
-C++ provides runtime polymorphism through virtual
-functions.  They are a very useful feature, but
-they do have some limitations.
-
-* They are intrusive.  In generic programming, we can
-  design an interface which allows third-party types
-  to be adapted to it.
-* They require dynamic memory management.  Of course,
-  most of the problems can be avoided by using an
-  appropriate smart pointer type. Even so, it still
-  acts like a pointer rather than a value.
-* Virtual functions' ability to apply multiple
-  independent concepts to a single object is limited.
-
-The Boost.TypeErasure library solves these problems
-allowing us to mirror static generic programming
-at runtime.
+The TypeErasure library provides runtime polymorphism
+in C++, superior to that provided by the core language.
 
-[note TypeErasure is not an official Boost library.]
-
-[import ../example/intro.cpp]
-[intro]
+We have two distinct kinds of polymorphism built in to C++,
+virtual functions and templates, which each have
+their own advantages and disadvantages.
+
+* Virtual functions are not resolved until runtime,
+  while templates are always resolved at compile
+  time.  If your types can vary at runtime (for
+  example, if they depend on user input), then
+  static polymorphism with templates doesn't help much.
+* Virtual functions can be used with separate compilation.
+  The body of a template has to be available
+  in every translation unit in which it is used,
+  slowing down compiles and increasing rebuilds.
+* Virtual function automatically make the requirements
+  on the aruments explicit.  Templates are only
+  checked when they're instantiated, requiring
+  extra work in testing, assertions, and documentation.
+* The compiler creates a new copy of each function
+  template every time it is instantiated.  This
+  allows better optimization, because the compiler
+  knows everything statically, but it also causes
+  a significant increase of binary sizes.
+* Templates support Value semantics.  Objects that
+  "behave like an int" and are not shared are easier
+  to reason about.  To use virtual functions, on
+  the other hand, you have to use (smart) pointers
+  or references.
+* Template libraries can allow third-party types to
+  be adapted non-intrusively for seamless interoperability.
+  With virtual functions, you have to create a wrapper
+  that inherits from the base class.
+* Templates can handle constraints involving
+  multiple types.  For example, std::for_each
+  takes an iterator range and a function that
+  can be called on the elements of the range.
+  Virtual functions aren't really able to
+  express such constraints.
+
+The Boost.TypeErasure library provides another set
+of trade-offs.  As with virtual functions, dispatching
+occurs at runtime and you can define a function once
+in a source file.  The requirements are stated up front
+in the form of a Concept.  Like templates, the library
+supports value semantics, non-intrusive adaptation, and
+requirements across multiple types.
+
+Boost includes several special cases of this kind
+of polymorphism:
+
+* `boost::any` for CopyConstructible types.
+* `boost::function` for objects that can be called like functions.
+* Boost.Range provides `any_iterator`.
+
+Boost.TypeErasure generalizes this to support arbitrary
+requirements and provides a
+[link boost_typeerasure.predef predefined set of common concepts]
 
 [endsect]
 
@@ -104,20 +143,34 @@
 [endsect]
 
 [section:basic Basic Usage]
+
 [import ../example/basic.cpp]
 [basic]
-[endsect]
 
-[section:multi Functions with Multiple Arguments]
-[import ../example/multi.cpp]
-[multi]
+[section Composing Concepts]
+[import ../example/compose.cpp]
+[compose]
 [endsect]
 
-[section:convert Conversions]
+[section Conversions]
 [import ../example/convert.cpp]
 [convert]
 [endsect]
 
+[endsect]
+
+[section:concept Concepts in Depth]
+
+[section:custom Defining Custom Concepts]
+[import ../example/custom.cpp]
+[custom]
+[endsect]
+
+[section:overload Overloading]
+[import ../example/overload.cpp]
+[overload]
+[endsect]
+
 [section:references Using References]
 [import ../example/references.cpp]
 [references]
@@ -128,16 +181,9 @@
 [construction]
 [endsect]
 
-[section:concept Concepts in Depth]
-
-[section:custom Defining Custom Concepts]
-[import ../example/custom.cpp]
-[custom]
-[endsect]
-
-[section:compose Composing Concepts]
-[import ../example/compose.cpp]
-[compose]
+[section:multi Functions with Multiple Arguments]
+[import ../example/multi.cpp]
+[multi]
 [endsect]
 
 [section:concept_map Concept Maps]
@@ -145,11 +191,6 @@
 [concept_map]
 [endsect]
 
-[section:overload Overloading]
-[import ../example/overload.cpp]
-[overload]
-[endsect]
-
 [section:overload Associated Types]
 [import ../example/associated.cpp]
 [associated]
@@ -217,29 +258,6 @@
 
 [endsect]
 
-[section:reserved Reserved Identifiers]
-
-The library reserves all names begining with
-`_boost_type_erasure` for use as members.  No
-class shall contain such a member except
-those defined by the library.
-
-The library reserves all identifiers begining
-with `BOOST_TYPE_ERASURE` for any use.
-
-FIXME: this is too broad.
-The library reserves all identifiers that
-are either a single upper case letter,
-a single upper case letter followed by
-a sequence of digits, in CamelCase, or
-underscore_separated for use in namespace
-`boost::type_erasure`. Such identifiers may
-not be defined as macros.  (Macros defined
-in system headers that I know about are
-excepted for the sake of pragmatism.).
-
-[endsect]
-
 [section:predef Predefined Concepts]
 
 In the following tables, `T` and `U` are the types that the operation
@@ -332,6 +350,19 @@
 with anything that a user might want.
 [endsect]
 
+[section:placeholder Why are the placeholders called `_a`, `_b` and not `_1` `_2`]
+
+An earlier version of the library used the names `_1`, `_2`, etc.
+instead of `_a`, `_b`, etc.  This caused a certain amount
+of confusion because the numbered placeholders are
+already used with a somewhat different meaning by several
+other libraries including Boost/Std Bind, Boost.Phoenix,
+and Boost.MPL.  I eventually decided that since the
+placeholders represented named parameters instead of positional parameters,
+letters were more appropriate than numbers.
+
+[endsect]
+
 [endsect]
 
 [section:design Design Notes]
@@ -515,19 +546,6 @@
 
 [endsect]
 
-[section:placeholder Placeholder Names]
-
-An earlier version of the library used the names `_1`, `_2`, etc.
-instead of `_a`, `_b`, etc.  This caused a certain amount
-of confusion because the numbered placeholders are
-already used by several other libraries including
-Boost/Std Bind, Boost.Phoenix, and Boost.MPL.  I
-eventually decided that since the placeholders represented
-named parameters instead of positional parameters,
-letters were more appropriate than numbers.
-
-[endsect]
-
 [endsect]
 
 [section:feedback Feedback Wanted]
@@ -594,7 +612,29 @@
 
 [section:acknowledgements Acknowledgements]
 
-* The name `any` was taken from Alexander Nasonov's
-  DynamicAny library.
+The name `any` was taken from Alexander Nasonov's
+DynamicAny library.
+
+Thanks to review manager, Lorenzo Caminiti
+and all who participated in the formal review:
+
+* Christophe Henry
+* Paul Bristow
+* Karsten Ahnert
+* Pete Bartlett
+* Sebastian Redl
+* Hossein Haeri
+* Trigve Siver
+* Julien Nitard
+* Eric Niebler
+* Fabio Fracassi
+* Joel de Guzman
+* Alec Chapman
+* Larry Evans
+* Vincente J. Botet Escriba
+* Marcus Werle
+* Andrey Semashev
+* Dave Abrahams
+* Thomas Jordan
 
 [endsect]

Modified: sandbox/type_erasure/libs/type_erasure/example/basic.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/basic.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/basic.cpp	2012-09-21 16:50:44 EDT (Fri, 21 Sep 2012)
@@ -22,11 +22,11 @@
     //[basic1
     /*`
         The main class in the library is __any.  We can just pass
-        it an MPL sequence containing all the concepts that we
-        wish to use.
+        it an MPL sequence specifying all the requirements on
+        the types that it can hold.
 
         [note The MPL sequence combines multiple concepts.
-        In the rare case when we only want one concept, it doesn't
+        In the rare case when we only want a single concept, it doesn't
         need to be wrapped in an MPL sequence.]
     */
     any<mpl::vector<copy_constructible<>, typeid_<> > > x(10);
@@ -44,7 +44,8 @@
     /*`
         Now, this example doesn't do very much.  `x` is approximately
         equivalent to a [@boost:/libs/any/index.html boost::any].
-        Let's add a few more features.
+        We can make it more interesting by adding some operators,
+        such as `operator++` and `operator<<`
     */
     any<
         mpl::vector<
@@ -59,9 +60,69 @@
     //]
 }
 
+//[basic3
+/*`
+    The library provides a full set of operators, but this
+    obviously won't cover all use cases;  we often need to
+    define our own requirements.  Let's take the `push_back`
+    method, defined by several STL containers.
+*/
+
+BOOST_TYPE_ERASURE_MEMBER((has_push_back), push_back, 1)
+
+void append_many(any<has_push_back<void(int)>, _self&> container) {
+    for(int i = 0; i < 10; ++i)
+        container.push_back(i);
+}
+
+/*`
+    There are a few things to note about this.  First,
+    we use the macro __BOOST_TYPE_ERASURE_MEMBER to
+    define a concept called `has_push_back` for a
+    member function called `push_back` which takes
+    one argument.  When we use `has_push_back`, we have to
+    give it the signature of the function, `void(int)`.
+    This means that we expect to find a function
+    that looks like:
+
+    ``
+    void push_back(int);
+    ``
+
+    Thus, we could call `append_many` with `std::vector<int>`,
+    `std::list<int>`, or `std::vector<long>` (because `int` is
+    convertible to `long`), but not `std::list<std::string>`
+    or `std::set<int>`.
+
+    Also, note the use of `_self&` as the second argument of
+    __any.  `_self` is a __placeholder.  By using it here,
+    we indicate that the __any stores a reference
+    to another object instead of owning its own object.
+*/
+
+/*`
+    For free functions, we can use __BOOST_TYPE_ERASURE_FREE.
+*/
+
+BOOST_TYPE_ERASURE_FREE((has_swap), swap, 2);
+template<class T = _self>
+struct swappable : mpl::vector<has_swap<void(T&, T&)> > {};
+
+/*`
+    We use the __placeholder `_self` here to indicate which arguments
+    of `swap` should be any's.  When we use swap, we want it
+    to look like `has_swap<void(_self&, _self&)>`, since `swap`
+    takes two arguments of the same type by reference.  Since
+    the signature of swap always looks like this, we define
+    `swappable<>` as a convenient short-cut.
+*/
+
+//]
+
 //[basic
 //` (For the source of the examples in this section see
 //` [@boost:/libs/type_erasure/example/basic.cpp basic.cpp])
 //` [basic1]
 //` [basic2]
+//` [basic3]
 //]

Modified: sandbox/type_erasure/libs/type_erasure/example/custom.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/custom.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/custom.cpp	2012-09-21 16:50:44 EDT (Fri, 21 Sep 2012)
@@ -18,14 +18,16 @@
 
 //[custom1
 /*`
-    Let's define a concept to allow push_back on a sequence.
-    To do this, we create a class template with a template
-    parameter for each argument, and a static member function
+    Earlier, we used __BOOST_TYPE_ERASURE_MEMBER to define
+    a concept for containers that support `push_back`.  Let's
+    take a look at what this actually entails.  The first thing
+    we need is a class template with a template parameter for
+    each argument, and a static member function
     called `apply` that calls `push_back`.
 */
 
 template<class C, class T>
-struct push_back
+struct has_push_back
 {
     static void apply(C& cont, const T& arg) { cont.push_back(arg); }
 };
@@ -48,10 +50,10 @@
 namespace boost {
 namespace type_erasure {
 template<class C, class T, class Base>
-struct concept_interface< ::push_back<C, T>, Base, C> : Base
+struct concept_interface<has_push_back<C, T>, Base, C> : Base
 {
     void push_back(typename rebind_any<Base, const T&>::type arg)
-    { call(::push_back<C, T>(), *this, arg); }
+    { call(has_push_back<C, T>(), *this, arg); }
 };
 }
 }
@@ -64,9 +66,9 @@
         __call to dispatch the operation.
     */
     std::vector<int> vec;
-    any<push_back<_self, int>, _self&> c(vec);
+    any<has_push_back<_self, int>, _self&> c(vec);
     int i = 10;
-    call(push_back<_self, int>(), c, i);
+    call(has_push_back<_self, int>(), c, i);
     // vec is [10].
     //]
 }
@@ -81,7 +83,7 @@
         now becomes
     */
     std::vector<int> vec;
-    any<push_back<_self, int>, _self&> c(vec);
+    any<has_push_back<_self, int>, _self&> c(vec);
     c.push_back(10);
     /*`
         which is what we want.

Modified: sandbox/type_erasure/libs/type_erasure/example/overload.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/overload.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/overload.cpp	2012-09-21 16:50:44 EDT (Fri, 21 Sep 2012)
@@ -19,8 +19,10 @@
 
 //[overload1
 /*`
-    Sometimes we want to use the same concept several times
-    with different parameters.  Specializing __concept_interface
+    __concept_interface allows us to inject arbitrary declarations
+    into an __any.  This is very flexible, but there are some pitfalls
+    to watch out for.  Sometimes we want to use the same concept several
+    times with different parameters.  Specializing __concept_interface
     in a way that handles overloads correctly is a bit tricky.
     Given a concept foo, we'd like the following to work:
 
@@ -147,7 +149,10 @@
     __rebind_any, then we could end up violating the one definition
     rule by defining the same function twice.  Similarly, we use
     SFINAE in the second specialization to make sure that bar is
-    only defined once when both arguments are placeholders.
+    only defined once when both arguments are placeholders.  It's
+    possible to merge the two specializations with a bit of metaprogramming,
+    but unless you have a lot of arguments, it's probably not
+    worth while.
     
     At first I tried overloading `bar` at namespace scope.  This
     seems like a more obvious solution at first.  Don't use it.