[Boost-commit] svn:boost r85153 - trunk/libs/coroutine/doc

Subject: [Boost-commit] svn:boost r85153 - trunk/libs/coroutine/doc
From: oliver.kowalke_at_[hidden]
Date: 2013-07-24 12:29:09

Author: olli
Date: 2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)
New Revision: 85153
URL: http://svn.boost.org/trac/boost/changeset/85153

Log:
coroutine: documentation updated

Text files modified: 
   trunk/libs/coroutine/doc/coro.qbk       |     1                                         
   trunk/libs/coroutine/doc/coroutine.qbk  |     2                                         
   trunk/libs/coroutine/doc/intro.qbk      |    10                                         
   trunk/libs/coroutine/doc/motivation.qbk |   201 ++++---                                 
   trunk/libs/coroutine/doc/old.qbk        |     2                                         
   trunk/libs/coroutine/doc/unidirect.qbk  |   988 ++++++++++++++++++--------------------- 
   6 files changed, 585 insertions(+), 619 deletions(-)

Modified: trunk/libs/coroutine/doc/coro.qbk
==============================================================================
--- trunk/libs/coroutine/doc/coro.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/coro.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -70,6 +70,7 @@
 [def __handle_read__ ['session::handle_read()]]
 [def __io_service__ ['boost::asio::io_sevice]]
 [def __pull_coro_get__ ['boost::coroutines::coroutine<>::pull_type::get()]]
+[def __pull_coro_it__ ['boost::coroutines::coroutine<>::pull_type::iterator]]
 [def __pull_coro_op__ ['boost::coroutines::coroutine<>::pull_type::operator()]]
 [def __push_coro_op__ ['boost::coroutines::coroutine<>::push_type::operator()]]
 [def __server__ ['server]]

Modified: trunk/libs/coroutine/doc/coroutine.qbk
==============================================================================
--- trunk/libs/coroutine/doc/coroutine.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/coroutine.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -8,7 +8,7 @@
 [section:coroutine Coroutine]
 
 __boost_coroutine__ provides two interfaces - one with uni- and one with bidirectional
-data transfer.
+data transfer (deprecated).
 
 [include unidirect.qbk]
 [include old.qbk]

Modified: trunk/libs/coroutine/doc/intro.qbk
==============================================================================
--- trunk/libs/coroutine/doc/intro.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/intro.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -94,4 +94,14 @@
 routine called by that top-level routine may not itself suspend. This prohibits
 providing suspend/resume operations in routines within a general-purpose library.
 
+[heading first-class continuation]
+A first-class continuation can be passed as an argument, returned by a
+function and stored in a data structure to be used later.
+In some implementations (for instance C# ['yield]) the continuation can
+not be directly accessed or directly manipulated.
+
+Without stackfulness and first-class semantics some useful execution control
+flows cannot be supported (for instance cooperative multitasking or
+checkpointing).
+
 [endsect]

Modified: trunk/libs/coroutine/doc/motivation.qbk
==============================================================================
--- trunk/libs/coroutine/doc/motivation.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/motivation.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -27,93 +27,134 @@
 trees is different.
 
 The same fringe problem could be solved using coroutines by iterating over the
-leaf nodes and comparing this sequence via \cpp{std::equal()}. The range of leaf
-nodes is generated by a visitor which recursively traverses the tree and passes
-leaf nodes to its coroutine.
-
-        node::ptr_t create_tree1(){
-            return branch::create(
-                leaf::create("a"),
-                branch::create(
-                    leaf::create("b"),
-                    leaf::create("c")));
-        }
-
-        node::ptr_t create_tree2(){
-            return branch::create(
-                branch::create(
-                    leaf::create("a"),
-                    leaf::create("b")),
-                leaf::create("c"));
-        }
-
-        // create tree t1
-        node::ptr_t t1=create_tree1();
-        // create a coroutine, recursivly iterates trough t1
-        // returning leaf nodes
-        std::coroutine<leaf&>::pull_type c1(
-            [&](std::coroutine<leaf&>::push_type& c){
-                // create visitor, attached to coroutine
-                coro_visitor v(c);
-                // traverse t1 recursivly
-                t1->accept(v);
-            });
-
-        // create tree t2
-        node::ptr_t t2=create_tree2();
-        // create a coroutine, recursivly iterates trough t2
-        // returning leaf nodes
-        std::coroutine<leaf&>::pull_type c2(
-            [&](std::coroutine<leaf&>::push_type& c){
-                // create visitor, attached to coroutine
-                coro_visitor v(c);
-                // traverse t2 recursivly
-                t2->accept(v);
-            });
-
-        // compare leaf node ranges of t1 and t2
-        bool result = std::equal(
-                std::begin(c1),
-                std::end(c1),
-                std::begin(c2));
-
-        std::cout << std::boolalpha << "same fringe == " << result;
-
-A tree consists of branch and leaf nodes. Each branch node has two children;
-leaf nodes have none. Trees t1 and t2 have a different tree structure but the
-same fringe.
-For each tree a __pull_coro__ is created while in the associated __coro_fn__
-['coro_visitor] traverses the tree.
-__pull_coro__-iterator, created from __pull_coro__, steps over the leaf nodes of its tree
-and ['std::equal()] compares the iterator ranges.
-
-        class coro_visitor : public visitor
-        {
-        private:
-            // coroutine used to pass leaf node back to caller
-            std::coroutine<leaf&>::push_type & c_;
-
-        public:
-            coro_visitor(std::coroutine<leaf&>::push_type& c) :
-                c_(c)
+leaf nodes and comparing this sequence via \cpp{std::equal()}. The range of data
+values is generated by function ['traverse()] which recursively traverses the
+tree and passes each node's data value to its __push_coro__.
+__push_coro__ suspends the recursive computation and transfers the data value to
+the main execution context.
+__pull_coro_it__, created from __pull_coro__, steps over those data values and
+delivers them to  ['std::equal()] for comparison. Each increment of __pull_coro_it__
+resumes ['traverse()]. Upon return from ['iterator::operator++()], either
+a new data value is available, or tree traversal is finished (iterator is
+invalidated).
+
+        struct node{
+            typedef std::shared_ptr<node> ptr_t;
+
+            // Each tree node has an optional left subtree,
+            // an optional right subtree and a value of its own.
+            // The value is considered to be between the left
+            // subtree and the right.
+            ptr_t       left,right;
+            std::string value;
+
+            // construct leaf
+            node(const std::string& v):
+                left(),right(),value(v)
+            {}
+            // construct nonleaf
+            node(ptr_t l,const std::string& v,ptr_t r):
+                left(l),right(r),value(v)
             {}
 
-            void visit(branch & b){
-                // traverse tree
-                if (b.left) b.left->accept(*this);
-                if (b.right) b.right->accept(*this);
+            static ptr_t create(const std::string& v){
+                return ptr_t(new node(v));
             }
 
-            void visit(leaf & l){
-                // return leaf node to caller
-                c_(l);
+            static ptr_t create(ptr_t l,const std::string& v,ptr_t r){
+                return ptr_t(new node(l,v,r));
             }
         };
 
-The visitor inspects recursively the tree - on each leaf node it escapes the
-recursive computation and makes the leaf node available to the iterator (via
-__push_coro__). After re-entering the visitor the recursive traversing of the tree
-continues.
+        node::ptr_t create_left_tree_from(const std::string& root){
+            /* --------
+                 root
+                 / \
+                b   e
+               / \
+              a   c
+             -------- */
+            return node::create(
+                    node::create(
+                        node::create("a"),
+                        "b",
+                        node::create("c")),
+                    root,
+                    node::create("e"));
+        }
+
+        node::ptr_t create_right_tree_from(const std::string& root){
+            /* --------
+                 root
+                 / \
+                a   d
+                   / \
+                  c   e
+               -------- */
+            return node::create(
+                    node::create("a"),
+                    root,
+                    node::create(
+                        node::create("c"),
+                        "d",
+                        node::create("e")));
+        }
+
+        // recursively walk the tree, delivering values in order
+        void traverse(node::ptr_t n,
+                      boost::coroutines::coroutine<std::string>::push_type& out){
+            if(n->left) traverse(n->left,out);
+            out(n->value);
+            if(n->right) traverse(n->right,out);
+        }
+
+        // evaluation
+        {
+            node::ptr_t left_d(create_left_tree_from("d"));
+            boost::coroutines::coroutine<std::string>::pull_type left_d_reader(
+                [&]( boost::coroutines::coroutine<std::string>::push_type & out){
+                    traverse(left_d,out);
+                });
+
+            node::ptr_t right_b(create_right_tree_from("b"));
+            boost::coroutines::coroutine<std::string>::pull_type right_b_reader(
+                [&]( boost::coroutines::coroutine<std::string>::push_type & out){
+                    traverse(right_b,out);
+                });
+
+            std::cout << "left tree from d == right tree from b? "
+                      << std::boolalpha
+                      << std::equal(std::begin(left_d_reader),
+                                    std::end(left_d_reader),
+                                    std::begin(right_b_reader))
+                      << std::endl;
+        }
+        {
+            node::ptr_t left_d(create_left_tree_from("d"));
+            boost::coroutines::coroutine<std::string>::pull_type left_d_reader(
+                [&]( boost::coroutines::coroutine<std::string>::push_type & out){
+                    traverse(left_d,out);
+                });
+
+            node::ptr_t right_x(create_right_tree_from("x"));
+            boost::coroutines::coroutine<std::string>::pull_type right_x_reader(
+                [&]( boost::coroutines::coroutine<std::string>::push_type & out){
+                    traverse(right_x,out);
+                });
+
+            std::cout << "left tree from d == right tree from x? "
+                      << std::boolalpha
+                      << std::equal(std::begin(left_d_reader),
+                                    std::end(left_d_reader),
+                                    std::begin(right_x_reader))
+                      << std::endl;
+        }
+        std::cout << "Done" << std::endl;
+
+        output:
+        left tree from d == right tree from b? true
+        left tree from d == right tree from x? false
+        Done
 
 
 [heading asynchronous operations with boost.asio]

Modified: trunk/libs/coroutine/doc/old.qbk
==============================================================================
--- trunk/libs/coroutine/doc/old.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/old.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -8,7 +8,7 @@
 [section:old Bidirectional coroutine (['deprecated])]
 
 [note This interface is deprecated but can be used by compiling the code with
-macro BOOST_COROUTINES_OLD.]
+compiler flag BOOST_COROUTINES_OLD.]
 
 Each instance of __coro__ has its own context of execution (CPU registers and
 stack space) or represents __not_a_coro__ (similar to __thread__).

Modified: trunk/libs/coroutine/doc/unidirect.qbk
==============================================================================
--- trunk/libs/coroutine/doc/unidirect.qbk	Wed Jul 24 11:33:51 2013	(r85152)
+++ trunk/libs/coroutine/doc/unidirect.qbk	2013-07-24 12:29:09 EDT (Wed, 24 Jul 2013)	(r85153)
@@ -9,438 +9,314 @@
 
 [note This is the default interface (macro BOOST_COROUTINES_UNIDIRECT).]
 
-Two kinds of __coros__ are provided - __push_coro__ for transfering data to
-and __pull_coro__ for transfering data from the other execution context.
-Both coroutine flavours occure in a pair - providing a unidirectional data
-transfer.
-
-Each instance of __coro__ has its own context of execution (CPU registers and
-stack space) or represents __not_a_coro__ (similar to __thread__).
-Objects of type __coro__ are moveable but not copyable and can be returned by a
-function.
+Two coroutine types - __push_coro__ and __pull_coro__ - providing a
+unidirectional transfer of data.
 
-        boost::coroutines::coroutine< int >::push_type f();
 
-        void g()
-        {
-            boost::coroutines::coroutine< int >::push_type c( f() );
-            c( 1);
-        }
-
-[note __boost_move__ is used to emulate rvalue references.]
-
-
-[heading Creating a coroutine]
-
-A new __coro__ is created from a __coro_fn__ (function or functor) which will be
-executed in a new __ctx__ (CPU registers and stack space).
-
-[note __coro_fn__ is required to return ['void] and accept a reference of type
-__push_coro__ (if called by __pull_coro__) or vice versa.]
-
-The template argument determines the data-type transferred to/from
-__coro_fn__.
-
-        void f( boost:::coroutines::coroutine< std::string >::pull_type & c)
-        {
-            // access argument
-            std::string str( c.get() );
-            // return to other execution context
-            c();
-        }
-
-        std::string str;
-        boost::coroutines::coroutine< std::string >::push_type c( f);
-        // pass argument
-        c( str);
-
-
-The __coro_fn__ is started at __coro__ construction (similar to __thread__)
-in a newly created __pull_coro__ complete with registers, flags, stack and
-instruction pointer. In the case of __push_coro__ the __coro_fn__ is entered
-when __push_coro_op__ is called the first time.
-
-__attrs__, an additional constructor argument of __coro__, defines the stack
-size, stack unwinding and floating-point preserving behaviour used for __ctx__
-construction.
-
-The __coro__ constructor uses the __stack_allocator_concept__ to allocate an
-associated stack, and the destructor uses the same __stack_allocator_concept__
-to deallocate the stack.  The default __stack_allocator_concept__ is
-__stack_allocator__, but a custom stack-allocator can be passed to the
-constructor.
-
-
-[heading Calling a coroutine]
-
-Using __pull_coro__ requires that __coro_fn__ takes __push_coro__ as first
-argument and vice versa.
-For __pull_coro__ __coro_fn__ is entered at construction and if control should
-be returned to the original calling routine __push_coro_op__ (first argument of
-__coro_fn__) has to be invoked.
-
-        void f( boost::coroutines::coroutine< std::string >::push_type & c)
-        {
-            c("abc");
-        }
-
-        boost::coroutines::coroutine< std::string >::pull_type c( f);
-        std::string str = c.get();
-        c();
-
-Multiple arguments are wrapped into __tuple__.
-
-        void g( boost::coroutines::coroutine< boost::tuple< X, Y > >::pull_type & c);
-        boost::coroutines::coroutine< boost::tuple< X, Y > >::push_type c( g);
-
-
-The current coroutine information (registers, flags, and stack and instruction
-pointer) is saved and the original context information is restored. Calling
-__push_coro_op__/__pull_coro_op__ resumes execution in the coroutine after
-saving the new state of the original routine.
-
-        void fn( boost::coroutines::coroutine< void >::pull_type & c, int j)
-        {
-            for( int i = 0; i < j; ++i)
-            {
-                std::cout << "fn(): local variable i == " << i << std::endl;
-
-                // save current coroutine
-                // value of local variable is preserved
-                // transfer execution control back to main()
-                c();
-
-                // coroutine<>::push_type<>::operator()() was called
-                // execution control transferred back from main()
-            }
-        }
-
-        int main( int argc, char * argv[])
-        {
-            // bind parameter '7' to coroutine-fn
-            boost::coroutines::coroutine< void >::push_type c( boost::bind( fn, _1, 7) );
-
-            std::cout << "main() starts coroutine c" << std::endl;
-
-            while ( c)
-            {
-                std::cout << "main() calls coroutine c" << std::endl;
-                // execution control is transferred to c
-                c();
-            }
-
-            std::cout << "Done" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
-
-        output:
-            main() starts coroutine c
-            fn(): local variable i == 0
-            main() calls coroutine c
-            fn(): local variable i == 1
-            main() calls coroutine c
-            fn(): local variable i == 2
-            main() calls coroutine c
-            fn(): local variable i == 3
-            main() calls coroutine c
-            fn(): local variable i == 4
-            main() calls coroutine c
-            fn(): local variable i == 5
-            main() calls coroutine c
-            fn(): local variable i == 6
-            main() calls coroutine c
-            Done
-
-[warning Calling __push_coro_op__/__pull_coro_op__ from inside the [_same]
-coroutine results in undefined behaviour.]
-
-
-[heading Transfer of data]
-
-The template argument of __push_coro__, defines the types transferred
-to and in the case of __pull_coro__ the type transfered from
-__coro_fn__.
-
-__push_coro_op__ accepts argument defined as template argument and returns a
-refernce to __push_coro__.
-The arguments passed to __push_coro_op__, in one coroutine, is returned by
-__pull_coro_get__ in the other execution context.
-
-The value given to __push_coro_op__, in one coroutine, is returned by
-__pull_coro_get__ in the other routine.
-
-        void fn( boost::coroutines::coroutine< int >::pull_type & c)
-        {
-            // access the integer argument passed to coroutine< int >::push_type::operator()
-            int i = c.get();
-            std::cout << "fn(): local variable i == " << i << std::endl;
-
-            // save current coroutine context and
-            // transfer execution control back to caller
-            // after execution control returns from coroutine< int >::pull_type::operator()
-            // the transferred integer s accessed via coroutine< int >::pull_type::get()
-            i = c().get();
-
-            // i == 10 because c( 10) in main()
-            std::cout << "fn(): local variable i == " << i << std::endl;
-        }
-
-        int main( int argc, char * argv[])
-        {
-            std::cout << "main(): call coroutine c" << std::endl;
-            boost::coroutines::coroutine< int >::push_type c( fn);
-
-            c( 7);
-            c( 10);
-
-            std::cout << "Done" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
-
-        output:
-            main(): call coroutine c
-            fn(): local variable i == 7
-            fn(): local variable i == 10
-            Done
-
-
-[heading __coro_fn__ with multiple arguments]
-
-__tuple__ can be used to transfer mutliple data types.
-
-        void fn( boost::coroutines::coroutine< boost::tuple< int, int > >::pull_type & c)
-        {
-            int a, b;
-            boost::tie( a, b) = c.get();
-            std::cout << "main(): " << a << " + " << b << " == " << a + b << std::endl;
-            boost::tie( a, b) = c().get();
-            std::cout << "main(): " << a << " + " << b << " == " << a + b << std::endl;
-        }
-
-        int main( int argc, char * argv[])
-        {
-            std::cout << "main(): call coroutine c" << std::endl;
-            boost::coroutines::coroutine< boost::tuple< int, int > >::push_typec( fn);
-
-            c( boost::make_tuple( 3, 7) );
-            c( boost::make_tuple( 5, 7) );
-
-            std::cout << "Done" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
-
-        output:
-            main(): call coroutine c
-            main(): 3 + 7 == 10
-            main(): 5 + 7 == 12
-            Done
-
-
-[heading Transfer of pointers and references]
-
-You can transfer references and pointers from and to coroutines but as usual
-you must take care (scope, no re-assignment of const references etc.).
-In the following code `x` points to `local` which is allocated on stack of
-`c`. When `c` goes out of scope the stack becomes deallocated. Using `x`
-after `c` is gone will fail!
-
-        struct X
-        {
-            void g();
-        };
-
-
-        void fn( boost::coroutines::coroutine< X* >::push_type & ca) {
-            X local;
-            ca( & local);
-        }
-
-        int main() {
-            X * x = 0;
-            {
-                boost::coroutines::coroutine< X* >::pull_type c( fn);
-                x = c.get(); // let x point to X on stack owned by c
-                // stack gets unwound -> X will be destructed
-            }
-            x->g(); // segmentation fault!
-            return EXIT_SUCCESS;
-        }
-
-
-[heading Range iterators]
-
-__boost_coroutine__ provides output- and input-iterators using __boost_range__.
-__pull_coro__ can be used via output-iterators using __begin__ and __end__.
-
-        typedef boost::range_iterator<
-            boost::coroutines::coroutine< int >::pull_type
-        >::type                                                 iterator_t;
+[heading __pull_coro__]
+__pull_coro__ transfers data from another execution context (== pulled-from).
+The class has only one template parameter defining the transferred parameter
+type.
+The constructor of __pull_coro__ takes a function (__coro_fn__) accepting a
+reference to a __push_coro__ as argument. Instantiating a __pull_coro__ passes
+the control of execution to __coro_fn__ and a complementary __push_coro__ is
+synthesized by the runtime and passed as reference to __coro_fn__.
+
+This kind of coroutine provides __pull_coro_op__. This method only switches
+context; it transfers no data.
+
+__pull_coro__ provides input iterators (__pull_coro_it__) and __begin__/__end__
+are overloaded. The increment-operation switches the context and transfers data.
+
+        std::coroutine<int>::pull_type source(
+            [&](std::coroutine<int>::push_type& sink){
+                int first=1,second=1;
+                sink(first);
+                sink(second);
+                for(int i=0;i<8;++i){
+                    int third=first+second;
+                    first=second;
+                    second=third;
+                    sink(third);
+                }
+            });
 
-        void power( boost::coroutines::coroutine< int >::push_type & c, int number, int exponent)
-        {
-            int counter = 0;
-            int result = 1;
-            while ( counter++ < exponent)
-            {
-                    result = result * number;
-                    c( result);
-            }
-        }
+        for(auto i:source)
+            std::cout << i <<  " ";
 
-        int main()
-        {
-            boost::coroutines::coroutine< int >::pull_type c( boost::bind( power, _1, 2, 8) );
-            iterator_t e( boost::end( c) );
-            for ( iterator_t i( boost::begin( c) ); i != e; ++i)
-                std::cout << * i <<  " ";
-
-            std::cout << "\nDone" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
+        std::cout << "\nDone" << std::endl;
 
         output:
-            2 4 8 16 32 64 128 256
-            Done
-
-`BOOST_FOREACH` can be used to iterate over the coroutine range too.
+        1 1 2 3 5 8 13 21 34 55
+        Done
 
-        typedef boost::range_iterator<
-            boost::coroutines::coroutine< int >::pull_type
-        >::type                                                 iterator_t;
-
-        void power( boost::coroutines::coroutine< int >::push_type & c, int number, int exponent)
-        {
-            int counter = 0;
-            int result = 1;
-            while ( counter++ < exponent)
-            {
-                    result = result * number;
-                    c( result);
+In this example a __pull_coro__ is created in the main execution context taking
+a lambda function (== __coro_fn__) which calculates Fibonacci numbers in a
+simple ['for]-loop).
+The __coro_fn__ is executed in a newly created execution context which is
+managed by the instance of __pull_coro__.
+A __push_coro__ is automatically generated by the runtime and passed as
+reference to the lambda function. Each time the lambda function calls
+__push_coro__op with another Fibonacci number, __push_coro__ transfers it back
+to the main execution context. The local state of __coro_fn__ is preserved and
+will be restored upon transferring execution control back to __coro_fn__
+to calculate the next Fibonacci number.
+Because __pull_coro__ provides input iterators and __begin__/__end__ are
+overloaded, a ['range-based for]-loop can be used to iterate over the generated
+Fibonacci numbers.
+
+
+[heading __push_coro__]
+__push_coro__ transfers data to the other execution context (== pushed-to).
+The class has only one template parameter defining the transferred parameter
+type.
+The constructor of __push_coro__ takes a function (__coro_fn__) accepting a
+reference to a __pull_coro__ as argument. In contrast to __pull_coro__,
+instantiating a __push_coro__ does not pass the control of execution to
+__coro_fn__ - instead the first call of __push_coro__op synthesizes a
+complementary __pull_coro__ and passes it as reference to __coro_fn__.
+
+The interface does not contain a ['get()]-function: you can not retrieve
+values from another execution context with this kind of coroutine.
+
+__push_coro__ provides output iterators (__push_coro__iterator) and
+__begin__/__end__ are overloaded. The increment-operation switches the context
+and transfers data.
+
+        struct FinalEOL{
+            ~FinalEOL(){
+                std::cout << std::endl;
             }
-        }
-
-        int main()
-        {
-            boost::coroutines::coroutine< int >::pull_type c( boost::bind( power, _1, 2, 8) );
-            BOOST_FOREACH( int i, c)
-            { std::cout << i <<  " "; }
-
-            std::cout << "\nDone" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
-
-        output:
-            2 4 8 16 32 64 128 256
-            Done
-
-
-Input iterators can be created from __push_coro__.
-
-
-
-[heading Exit a __coro_fn__]
-
-__coro_fn__ is exited with a simple return statement jumping back to the calling
-routine. The __pull_coro__/__push_coro__ becomes complete, e.g. __coro_bool__
-will return 'false'.
-
-        void power( boost::coroutines::coroutine< boost::tuple< int, int > >::pull_type & c, int number, int exponent)
-        {
-            int a, b;
-
-            boost::tie( a, b) = ca.get();
-            std::cout << "main(): " << a << " + " << b " == " << a + b << std::endl;
-            c();
-
-            boost::tie( a, b) = ca.get();
-            std::cout << "main(): " << a << " + " << b " == " << a + b << std::endl;
-            c();
-        }
-
-        int main( int argc, char * argv[])
-        {
-            std::cout << "main(): call coroutine c" << std::endl;
-            boost::coroutines::coroutine< boost::tuple< int, int > >::push_type c( power);
-            c( boost::make_tuple( 3, 7) );
-            BOOST_ASSERT( c);
-
-            c( boot::make_tuple( 5, 7) );
-            BOOST_ASSERT( ! c);
+        };
 
-            std::cout << "Done" << std::endl;
+        const int num=5, width=15;
+        std::coroutine<std::string>::push_type writer(
+            [&](std::coroutine<std::string>::pull_type& in){
+                // finish the last line when we leave by whatever means
+                FinalEOL eol;
+                // pull values from upstream, lay them out 'num' to a line
+                for (;;){
+                    for(int i=0;i<num;++i){
+                        // when we exhaust the input, stop
+                        if(!in) return;
+                        std::cout << std::setw(width) << in.get();
+                        // now that we've handled this item, advance to next
+                        in();
+                    }
+                    // after 'num' items, line break
+                    std::cout << std::endl;
+                }
+            });
+
+        std::vector<std::string> words{
+            "peas", "porridge", "hot", "peas",
+            "porridge", "cold", "peas", "porridge",
+            "in", "the", "pot", "nine",
+            "days", "old" };
 
-            return EXIT_SUCCESS;
-        }
+        std::copy(std::begin(words),std::end(words),std::begin(writer));
 
         output:
-            main(): call coroutine c
-            main(): 3 + 7 == 10
-            main(): 5 + 7 == 12
-            Done
-
-[important After returning from __coro_fn__ the __coro__ is complete (can not
-resumed with __coro_op__).]
+                   peas       porridge            hot           peas       porridge
+                   cold           peas       porridge             in            the
+                    pot           nine           days            old
+
+In this example a __push_coro__ is created in the main execution context
+accepting a lambda function (== __coro_fn__) which requests strings and lays out
+'num' of them on each line.
+This demonstrates the inversion of control permitted by coroutines. Without
+coroutines, a utility function to perform the same job would necessarily
+accept each new value as a function parameter, returning after processing that
+single value. That function would depend on a static state variable. A
+__coro_fn__, however, can request each new value as if by calling a function
+-- even though its caller also passes values as if by calling a function.
+The __coro_fn__ is executed in a newly created execution context which is
+managed by the instance of __push_coro__.
+The main execution context passes the strings to the __coro_fn__ by calling
+__push_coro__op.
+A __pull_coro__ is automatically generated by the runtime and passed as
+reference to the lambda function. The __coro_fn__ accesses the strings passed
+from the main execution context by calling __pull_coro__get and lays those
+strings out on ['std::cout] according the parameters 'num' and 'width'.
+The local state of __coro_fn__ is preserved and will be restored after
+transferring execution control back to __coro_fn__.
+Because __push_coro__ provides output iterators and __begin__/__end__ are
+overloaded, the ['std::copy] algorithm can be used to iterate over the vector
+containing the strings and pass them one by one to the coroutine.
+
+
+[heading stackful]
+Each instance of a coroutine has its own stack.
+
+In contrast to stackless coroutines, stackful coroutines allow invoking the
+suspend operation out of arbitrary sub-stackframes, enabling escape-and-reenter
+recursive operations.
+
+
+[heading move-only]
+A coroutine is moveable-only.
+
+If it were copyable, then its stack with all the objects allocated on it
+would be copied too. That would force undefined behaviour if some of these
+objects were RAII-classes (manage a resource via RAII pattern). When the first
+of the coroutine copies terminates (unwinds its stack), the RAII class
+destructors will release their managed resources. When the second copy
+terminates, the same destructors will try to doubly-release the same resources,
+leading to undefined behavior.
+
+
+[heading clean-up]
+On coroutine destruction the associated stack will be unwound.
+
+The constructor of coroutine allows to pass an customized ['stack-allocator].
+['stack-allocator] is free to deallocate the stack or cache it for future usage
+(for coroutines created later).
+
+
+[heading segmented stack]
+__push_coro__ and __pull_coro__ does support segmented stacks (growing on
+demand).
+
+It is not always possible to estimated the required stack size - in most cases
+too much memory is allocated (waste of virtual address-space).
+
+At construction a coroutine starts with a default (minimal) stack size. This
+minimal stack size is the maximum of page size and the canonical size for signal
+stack (macro SIGSTKSZ on POSIX).
+
+At this time of writing only GCC (4.7)\cite{gccsplit} is known to support
+segmented stacks. With version 1.54 __boost_coroutine__ provides support for
+segmented stacks.
+
+The destructor releases the associated stack. The implementer is free to
+deallocate the stack or to cache it for later usage.
+
+
+[heading context switch]
+A coroutine saves and restores registers according to the underlying ABI on
+each context switch.
 
+Some applications do not use floating-point registers and can disable preserving
+fpu registers for performance reasons.
 
-[heading Exceptions in __coro_fn__]
+[note According to the calling convention the FPU registers are preserved by
+default.]
 
-An exception thrown inside __coro_fn__ will transferred via exception-pointer
-(see __boost_exception__ for details) and re-thrown by constructor or
-__coro_op__.
+On POSIX systems, the coroutine context switch does not preserve signal masks
+for performance reasons.
 
-        void f( boost::coroutines::coroutine< void >::push_type & c)
-        {
-            c();
-            throw std::runtime_error("abc");
-        }
+A context switch is done via __push_coro__op and __pull_coro__op.
 
-        int main( int argc, char * argv[])
-        {
-            boost::coroutines::coroutine< void >::pull_type c( f);
-            try
-            {
-                c();
-            }
-            catch ( std::exception const& e)
-            {
-                std::cout << "exception catched:" << e.what() << std::endl;
-                return EXIT_FAILURE;
-            }
+[warning Calling __push_coro_op__/__pull_coro_op__ from inside the [_same]
+coroutine results in undefined behaviour.]
 
-            std::cout << "Done" << std::endl;
 
-            return EXIT_SUCCESS;
-        }
+[heading coroutine-function]
+The __coro_fn__ returns ['void] and takes its counterpart-coroutine as
+argument, so that using the coroutine passed as argument to __coro_fn__ is the
+only way to transfer data and execution control back to the caller.
+Both coroutine types take the same template argument.
+For __pull_coro__ the __coro_fn__ is entered at __pull_coro__ construction.
+For __push_coro__ the __coro_fn__ is not entered at __push_coro__ construction
+but entered by the first invocation of __push_coro__op.
+After execution control is returned from __coro_fn__ the state of the
+coroutine can be checked via
+__pull_coro__bool returning true if the coroutine is still valid (__coro_fn__
+has not terminated). Unless T is void, true also implies that a data value is
+available.
+
+
+[heading passing data from a pull-coroutine to main-context]
+In order to transfer data from a __pull_coro__ to the main-context the framework
+synthesizes a __push_coro__ associated with the __pull_coro__ instance in the
+main-context. The synthesized __push_coro__ is passed as argument to __coro_fn__.\\
+The __coro_fn__ must call this __push_coro__op in order to transfer each
+data value back to the main-context.
+In the main-context, the __pull_coro__bool determines whether the coroutine is
+still valid and a data value is available or __coro_fn__ has terminated
+(__pull_coro__ is invalid; no data value available). Access to the transferred
+data value is given by __pull_coro__get.
+
+        std::coroutine<int>::pull_type source( // constructor enters coroutine-function
+            [&](std::coroutine<int>::push_type& sink){
+                sink(1); // push {1} back to main-context
+                sink(1); // push {1} back to main-context
+                sink(2); // push {2} back to main-context
+                sink(3); // push {3} back to main-context
+                sink(5); // push {5} back to main-context
+                sink(8); // push {8} back to main-context
+            });
+
+        while(source){            // test if pull-coroutine is valid
+            int ret=source.get(); // access data value
+            source();             // context-switch to coroutine-function
+        }
+
+
+[heading passing data from main-context to a push-coroutine]
+In order to transfer data to a __push_coro__ from the main-context the framework
+synthesizes a __pull_coro__ associated with the __push_coro__ instance in the
+main-context. The synthesized __pull_coro__ is passed as argument to __coro_fn__.
+The main-context must call this __push_coro__op in order to transfer each data
+value into the __coro_fn__.
+Access to the transferred data value is given by __pull_coro__get.
+
+        std::coroutine<int>::push_type sink( // constructor does NOT enter coroutine-function
+            [&](std::coroutine<int>::pull_type& source){
+                for (int i:source) {
+                    std::cout << i <<  " ";
+                }
+            });
+
+        std::vector<int> v{1,1,2,3,5,8,13,21,34,55};
+        for( int i:v){
+            sink(i); // push {i} to coroutine-function
+        }
+
+
+[heading accessing parameters]
+Parameters returned from or transferred to the __coro_fn__ can be accessed with
+__pull_coro__get.
+
+Splitting-up the access of parameters from context switch function enables to
+check if __pull_coro__ is valid after return from __pull_coro__op, e.g.
+__pull_coro__ has values and __coro_fn__ has not terminated.
+
+        std::coroutine<std::tuple<int,int>>::push_type sink(
+            [&](std::coroutine<std::tuple<int,int>>::pull_type& source){
+                // access tuple {7,11}; x==7 y==1
+                int x,y;
+                std::tie(x,y)=source.get();
+            });
+
+        sink(std::make_tuple(7,11));
+
+
+[heading exceptions]
+An exception thrown inside a __pull_coro__'s __coro_fn__ before its first call
+to __push_coro__op will be re-thrown by the __pull_coro__ constructor. After a
+__pull_coro__'s __coro_fn__'s first call to __push_coro__op, any subsequent
+exception inside that __coro_fn__ will be re-thrown by __pull_coro__op.
+__pull_coro__get does not throw.
 
-        output:
-            exception catched: abc
+An exception thrown inside a __push_coro__'s __coro_fn__ will be re-thrown by
+__push_coro__op.
 
 [important Code executed by coroutine must not prevent the propagation of the
 __forced_unwind__ exception.  Absorbing that exception will cause stack
 unwinding to fail.  Thus, any code that catches all exceptions must re-throw the
 pending exception.]
 
-        try
-        {
+        try {
             // code that might throw
-        }
-        catch( forced_unwind)
-        {
+        } catch(const forced_unwind&) {
             throw;
-        }
-        catch(...)
-        {
+        } catch(...) {
             // possibly not re-throw pending exception
         }
 
 
 [heading Stack unwinding]
-
 Sometimes it is necessary to unwind the stack of an unfinished coroutine to
 destroy local stack variables so they can release allocated resources (RAII
 pattern). The third argument of the coroutine constructor, `do_unwind`,
@@ -456,49 +332,37 @@
 
 After unwinding, a __coro__ is complete.
 
+        struct X {
+            X(){
+                std::cout<<"X()"<<std::endl;
+            }
 
-        struct X
-        {
-            X()
-            { std::cout << "X()" << std::endl; }
-
-            ~X()
-            { std::cout << "~X()" << std::endl; }
+            ~X(){
+                std::cout<<"~X()"<<std::endl;
+            }
         };
 
-        void fn( boost::coroutines::coroutine< void >::pull_type & c)
         {
-            X x;
+            boost::coroutines::coroutine<void>::push_type sink(
+                [&](boost::coroutines::coroutine<void>::pull_type& source){
+                    X x;
+                    for(int=0;;++i){
+                        std::cout<<"fn(): "<<i<<std::endl;
+                        // transfer execution control back to main()
+                        source();
+                    }
+                });
+
+            sink();
+            sink();
+            sink();
+            sink();
+            sink();
 
-            for ( int  = 0;; ++i)
-            {
-                std::cout << "fn(): " << i << std::endl;
-                // transfer execution control back to main()
-                c();
-            }
+            std::cout<<"c is complete: "<<std::boolalpha<<c.is_complete()<<"\n";
         }
 
-        int main( int argc, char * argv[])
-        {
-            {
-                boost::coroutines::coroutine< void >::push_type c( fn,
-                          boost::coroutines::attributes(
-                            boost::context::default_stacksize(),
-                            boost::coroutines::stack_unwind) );
-
-                c();
-                c();
-                c();
-                c();
-                c();
-
-                std::cout << "c is complete: " << std::boolalpha << c.is_complete() << "\n";
-            }
-
-            std::cout << "Done" << std::endl;
-
-            return EXIT_SUCCESS;
-        }
+        std::cout<<"Done"<<std::endl;
 
         output:
             X()
@@ -512,33 +376,70 @@
             ~X()
             Done
 
-[important You must not swallow __forced_unwind__ exceptions!]
 
+[heading Range iterators]
+__boost_coroutine__ provides output- and input-iterators using __boost_range__.
+__pull_coro__ can be used via input-iterators using __begin__ and __end__.
 
-[heading FPU preserving]
+        int number=2,exponent=8;
+        boost::coroutines::coroutine< int >::pull_type source(
+            [&]( boost::coroutines::coroutine< int >::push_type & sink){
+                int counter=0,result=1;
+                while(counter++<exponent){
+                    result=result*number;
+                    sink(result);
+                }
+            });
 
-Some applications do not use floating-point registers and can disable preserving
-fpu registers for performance reasons.
+        for (auto i:source)
+            std::cout << i <<  " ";
 
-[note According to the calling convention the FPU registers are preserved by default.]
+        std::cout << "\nDone" << std::endl;
 
+        output:
+            2 4 8 16 32 64 128 256
+            Done
 
-[section:push_coro Class `coroutine<>::push_type`]
+Output-iterators can be created from __push_coro__.
+
+        std::coroutine<int>::push_type sink(
+            [&](std::coroutine<int>::pull_type& source){
+                while(source){
+                    std::cout << source.get() <<  " ";
+                    source();
+                }
+            });
+
+        std::vector<int> v{1,1,2,3,5,8,13,21,34,55};
+        std::copy(std::begin(v),std::end(v),std::begin(sink));
+
+
+[heading Exit a __coro_fn__]
+__coro_fn__ is exited with a simple return statement jumping back to the calling
+routine. The __pull_coro__/__push_coro__ becomes complete, e.g. __coro_bool__
+will return 'false'.
+
+[important After returning from __coro_fn__ the __coro__ is complete (can not
+resumed with __coro_op__).]
+
+
+
+[section:pull_coro Class `coroutine<>::pull_type`]
 
     #include <boost/coroutine/coroutine.hpp>
 
-    template< typename Arg >
-    class coroutine<>::push_type
+    template< typename R >
+    class coroutine<>::pull_type
     {
     public:
-        push_type();
+        pull_type();
 
         template<
             typename Fn,
             typename StackAllocator = stack_allocator,
             typename Allocator = std::allocator< coroutine >
         >
-        push_type( Fn fn, attributes const& attr = attributes(),
+        pull_type( Fn fn, attributes const& attr = attributes(),
                    StackAllocator const& stack_alloc = StackAllocator(),
                    Allocator const& alloc = Allocator() );
 
@@ -547,42 +448,46 @@
             typename StackAllocator = stack_allocator,
             typename Allocator = std::allocator< coroutine >
         >
-        push_type( Fn && fn, attributes const& attr = attributes(),
+        pull_type( Fn && fn, attributes const& attr = attributes(),
                    StackAllocator stack_alloc = StackAllocator(),
                    Allocator const& alloc = Allocator() );
 
-        push_type( push_type && other);
+        pull_type( pull_type && other);
 
-        push_type & operator=( push_type && other);
+        pull_type & operator=( pull_type && other);
 
         operator unspecified-bool-type() const;
 
         bool operator!() const;
 
-        void swap( push_type & other);
+        void swap( pull_type & other);
 
         bool empty() const;
 
-        push_type & operator()( Arg arg);
+        pull_type & operator()();
+
+        bool has_result() const;
+
+        R get() const;
     };
 
-    template< typename Arg >
-    void swap( push_type< Arg > & l, push_type< Arg > & r);
+    template< typename R >
+    void swap( pull_type< R > & l, pull_type< R > & r);
 
-    template< typename Arg >
-    range_iterator< push_type< Arg > >::type begin( push_type< Arg > &);
+    template< typename R >
+    range_iterator< pull_type< R > >::type begin( pull_type< R > &);
 
-    template< typename Arg >
-    range_iterator< push_type< Arg > >::type end( push_type< Arg > &);
+    template< typename R >
+    range_iterator< pull_type< R > >::type end( pull_type< R > &);
 
-[heading `push_type()`]
+[heading `pull_type()`]
 [variablelist
 [[Effects:] [Creates a coroutine representing __not_a_coro__.]]
 [[Throws:] [Nothing.]]
 ]
 
 [heading `template< typename Fn, typename StackAllocator, typename Allocator >
-          push_type( Fn fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
+          pull_type( Fn fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
 [variablelist
 [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize()
 when ! is_stack_unbound().]]
@@ -590,10 +495,11 @@
 determines stack clean-up and preserving floating-point registers.
 For allocating/deallocating the stack `stack_alloc` is used and internal
 data are allocated by Allocator.]]
+[[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
 [heading `template< typename Fn, typename StackAllocator, typename Allocator >
-          push_type( Fn && fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
+          pull_type( Fn && fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
 [variablelist
 [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize()
 when ! is_stack_unbound().]]
@@ -601,16 +507,17 @@
 determines stack clean-up and preserving floating-point registers.
 For allocating/deallocating the stack `stack_alloc` is used and internal
 data are allocated by Allocator.]]
+[[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
-[heading `push_type( push_type && other)`]
+[heading `pull_type( pull_type && other)`]
 [variablelist
 [[Effects:] [Moves the internal data of `other` to `*this`.
 `other` becomes __not_a_coro__.]]
 [[Throws:] [Nothing.]]
 ]
 
-[heading `push_type & operator=( push_type && other)`]
+[heading `pull_type & operator=( pull_type && other)`]
 [variablelist
 [[Effects:] [Destroys the internal data of `*this` and moves the
 internal data of `other` to `*this`. `other` becomes __not_a_coro__.]]
@@ -638,73 +545,85 @@
 [[Throws:] [Nothing.]]
 ]
 
-[heading `push_type<> & operator()(Arg arg)`]
+[heading `pull_type<> & operator()()`]
 [variablelist
-[[Preconditions:] [operator unspecified-bool-type() returns true for `*this`.]
-[[Effects:] [Execution control is transferred to __coro_fn__ and the argument
-`arg` is passed to the coroutine-function.]]
+[[Preconditions:] [`*this` is not a __not_a_coro__.]]
+[[Effects:] [Execution control is transferred to __coro_fn__ (no parameter are
+passed to the coroutine-function).]]
 [[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
-[heading `void swap( push_type & other)`]
+[heading `bool has_result()`]
 [variablelist
-[[Effects:] [Swaps the internal data from `*this` with the values
-of `other`.]]
+[[Preconditions:] [`*this` is not a __not_a_coro__.]]
+[[Returns:] [If `*this` has a, the function returns true. Otherwise false.]]
 [[Throws:] [Nothing.]]
 ]
 
-[heading `T caller_type::operator()( R)`]
+[heading `R get()()`]
+
+    R    coroutine<R>::pull_type::get();
+    R&   coroutine<R&>::pull_type::get();
+    void coroutine<void>pull_type::get()=delete;
+
 [variablelist
-[[Effects:] [Gives execution control back to calling context by returning
-a value of type R. The return type of this function is a __tuple__ containing
-the arguments passed to __coro_op__.]]
+[[Preconditions:] [`*this` is not a __not_a_coro__.]]
+[[Returns:] [Returns data transferred from coroutine-function via
+__push_coro_op__.]]
+[[Throws:] [Nothing.]]
+]
+
+[heading `void swap( pull_type & other)`]
+[variablelist
+[[Effects:] [Swaps the internal data from `*this` with the values
+of `other`.]]
 [[Throws:] [Nothing.]]
 ]
 
 [heading Non-member function `swap()`]
 
-    template< typename Arg >
-    void swap( push_type< Arg > & l, push_type< Arg > & r);
+    template< typename R >
+    void swap( pull_type< R > & l, pull_type< R > & r);
 
 [variablelist
 [[Effects:] [As if 'l.swap( r)'.]]
 ]
 
-[heading Non-member function `begin( push_type< Arg > &)`]
-    template< typename Arg >
-    range_iterator< push_type< Arg > >::type begin( push_type< Arg > &);
+[heading Non-member function `begin( pull_type< R > &)`]
+    template< typename R >
+    range_iterator< pull_type< R > >::type begin( pull_type< R > &);
 
 [variablelist
-[[Returns:] [Returns a range-iterator (output-iterator).]]
+[[Returns:] [Returns a range-iterator (input-iterator).]]
 ]
 
-[heading Non-member function `end( push_type< Arg > &)`]
-    template< typename Arg >
-    range_iterator< push_type< Arg > >::type end( push_type< Arg > &);
+[heading Non-member function `end( pull_type< R > &)`]
+    template< typename R >
+    range_iterator< pull_type< R > >::type end( pull_type< R > &);
 
 [variablelist
-[[Returns:] [Returns a end range-iterator (output-iterator).]]
+[[Returns:] [Returns a end range-iterator (input-iterator).]]
 ]
 
 [endsect]
 
 
-[section:pull_coro Class `coroutine<>::pull_type`]
+[section:push_coro Class `coroutine<>::push_type`]
 
     #include <boost/coroutine/coroutine.hpp>
 
-    template< typename R >
-    class coroutine<>::pull_type
+    template< typename Arg >
+    class coroutine<>::push_type
     {
     public:
-        pull_type();
+        push_type();
 
         template<
             typename Fn,
             typename StackAllocator = stack_allocator,
             typename Allocator = std::allocator< coroutine >
         >
-        pull_type( Fn fn, attributes const& attr = attributes(),
+        push_type( Fn fn, attributes const& attr = attributes(),
                    StackAllocator const& stack_alloc = StackAllocator(),
                    Allocator const& alloc = Allocator() );
 
@@ -713,46 +632,42 @@
             typename StackAllocator = stack_allocator,
             typename Allocator = std::allocator< coroutine >
         >
-        pull_type( Fn && fn, attributes const& attr = attributes(),
+        push_type( Fn && fn, attributes const& attr = attributes(),
                    StackAllocator stack_alloc = StackAllocator(),
                    Allocator const& alloc = Allocator() );
 
-        pull_type( pull_type && other);
+        push_type( push_type && other);
 
-        pull_type & operator=( pull_type && other);
+        push_type & operator=( push_type && other);
 
         operator unspecified-bool-type() const;
 
         bool operator!() const;
 
-        void swap( pull_type & other);
+        void swap( push_type & other);
 
         bool empty() const;
 
-        pull_type & operator()();
-
-        bool has_result() const;
-
-        R get() const;
+        push_type & operator()( Arg&& arg);
     };
 
-    template< typename R >
-    void swap( pull_type< R > & l, pull_type< R > & r);
+    template< typename Arg >
+    void swap( push_type< Arg > & l, push_type< Arg > & r);
 
-    template< typename R >
-    range_iterator< pull_type< R > >::type begin( pull_type< R > &);
+    template< typename Arg >
+    range_iterator< push_type< Arg > >::type begin( push_type< Arg > &);
 
-    template< typename R >
-    range_iterator< pull_type< R > >::type end( pull_type< R > &);
+    template< typename Arg >
+    range_iterator< push_type< Arg > >::type end( push_type< Arg > &);
 
-[heading `pull_type()`]
+[heading `push_type()`]
 [variablelist
 [[Effects:] [Creates a coroutine representing __not_a_coro__.]]
 [[Throws:] [Nothing.]]
 ]
 
 [heading `template< typename Fn, typename StackAllocator, typename Allocator >
-          pull_type( Fn fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
+          push_type( Fn fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
 [variablelist
 [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize()
 when ! is_stack_unbound().]]
@@ -760,11 +675,10 @@
 determines stack clean-up and preserving floating-point registers.
 For allocating/deallocating the stack `stack_alloc` is used and internal
 data are allocated by Allocator.]]
-[[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
 [heading `template< typename Fn, typename StackAllocator, typename Allocator >
-          pull_type( Fn && fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
+          push_type( Fn && fn, attributes const& attr, StackAllocator const& stack_alloc, Allocator const& alloc)`]
 [variablelist
 [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize()
 when ! is_stack_unbound().]]
@@ -772,17 +686,16 @@
 determines stack clean-up and preserving floating-point registers.
 For allocating/deallocating the stack `stack_alloc` is used and internal
 data are allocated by Allocator.]]
-[[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
-[heading `pull_type( pull_type && other)`]
+[heading `push_type( push_type && other)`]
 [variablelist
 [[Effects:] [Moves the internal data of `other` to `*this`.
 `other` becomes __not_a_coro__.]]
 [[Throws:] [Nothing.]]
 ]
 
-[heading `pull_type & operator=( pull_type && other)`]
+[heading `push_type & operator=( push_type && other)`]
 [variablelist
 [[Effects:] [Destroys the internal data of `*this` and moves the
 internal data of `other` to `*this`. `other` becomes __not_a_coro__.]]
@@ -810,61 +723,62 @@
 [[Throws:] [Nothing.]]
 ]
 
-[heading `pull_type<> & operator()()`]
-[variablelist
-[[Preconditions:] [`*this` is not a __not_a_coro__.]]
-[[Effects:] [Execution control is transferred to __coro_fn__ (no parameter are
-passed to the coroutine-function).]]
-[[Throws:] [Exceptions thrown inside __coro_fn__.]]
-]
+[heading `push_type<> & operator()(Arg&& arg)`]
+
+        push_type& coroutine<Arg>::push_type::operator()(const Arg&);
+        push_type& coroutine<Arg>::push_type::operator()(Arg&&);
+        push_type& coroutine<Arg&>::push_type::operator()(Arg&);
+        push_type& coroutine<void>::push_type::operator()();
 
-[heading `bool has_result()`]
 [variablelist
-[[Preconditions:] [`*this` is not a __not_a_coro__.]]
-[[Returns:] [If `*this` has a, the function returns true. Otherwise false.]]
-[[Throws:] [Nothing.]]
+[[Preconditions:] [operator unspecified-bool-type() returns true for `*this`.]]
+[[Effects:] [Execution control is transferred to __coro_fn__ and the argument
+`arg` is passed to the coroutine-function.]]
+[[Throws:] [Exceptions thrown inside __coro_fn__.]]
 ]
 
-[heading `R get()()`]
+[heading `void swap( push_type & other)`]
 [variablelist
-[[Preconditions:] [`*this` is not a __not_a_coro__.]]
-[[Returns:] [Returns data transferred from coroutine-function via
-__push_coro_op__.]]
+[[Effects:] [Swaps the internal data from `*this` with the values
+of `other`.]]
 [[Throws:] [Nothing.]]
 ]
 
-[heading `void swap( pull_type & other)`]
+[heading `T caller_type::operator()( R)`]
 [variablelist
-[[Effects:] [Swaps the internal data from `*this` with the values
-of `other`.]]
+[[Effects:] [Gives execution control back to calling context by returning
+a value of type R. The return type of this function is a __tuple__ containing
+the arguments passed to __coro_op__.]]
 [[Throws:] [Nothing.]]
 ]
 
 [heading Non-member function `swap()`]
 
-    template< typename R >
-    void swap( pull_type< R > & l, pull_type< R > & r);
+    template< typename Arg >
+    void swap( push_type< Arg > & l, push_type< Arg > & r);
 
 [variablelist
 [[Effects:] [As if 'l.swap( r)'.]]
 ]
 
-[heading Non-member function `begin( pull_type< R > &)`]
-    template< typename R >
-    range_iterator< pull_type< R > >::type begin( pull_type< R > &);
+[heading Non-member function `begin( push_type< Arg > &)`]
+    template< typename Arg >
+    range_iterator< push_type< Arg > >::type begin( push_type< Arg > &);
 
 [variablelist
-[[Returns:] [Returns a range-iterator (input-iterator).]]
+[[Returns:] [Returns a range-iterator (output-iterator).]]
 ]
 
-[heading Non-member function `end( pull_type< R > &)`]
-    template< typename R >
-    range_iterator< pull_type< R > >::type end( pull_type< R > &);
+[heading Non-member function `end( push_type< Arg > &)`]
+    template< typename Arg >
+    range_iterator< push_type< Arg > >::type end( push_type< Arg > &);
 
 [variablelist
-[[Returns:] [Returns a end range-iterator (input-iterator).]]
+[[Returns:] [Returns a end range-iterator (output-iterator).]]
 ]
 
 [endsect]
 
+
+
 [endsect]