[/ Copyright Oliver Kowalke 2009. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ] [section:unidirect Unidirectional coroutine] [note This is the default interface (macro BOOST_COROUTINES_UNIDIRECT).] Two coroutine types - __push_coro__ and __pull_coro__ - providing a unidirectional transfer of data. [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. boost::coroutines::coroutine::pull_type source( [&](boost::coroutines::coroutine::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); } }); for(auto i:source) std::cout << i << " "; std::cout << "\nDone" << std::endl; output: 1 1 2 3 5 8 13 21 34 55 Done 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; } }; const int num=5, width=15; boost::coroutines::coroutine::push_type writer( [&](boost::coroutines::coroutine::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 words{ "peas", "porridge", "hot", "peas", "porridge", "cold", "peas", "porridge", "in", "the", "pot", "nine", "days", "old" }; std::copy(boost::begin(words),boost::end(words),boost::begin(writer)); output: 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. [note According to the calling convention the FPU registers are preserved by default.] On POSIX systems, the coroutine context switch does not preserve signal masks for performance reasons. A context switch is done via __push_coro_op__ and __pull_coro_op__. [warning Calling __push_coro_op__/__pull_coro_op__ from inside the [_same] coroutine results in undefined behaviour.] [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__. boost::coroutines::coroutine::pull_type source( // constructor enters coroutine-function [&](boost::coroutines::coroutine::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__. boost::coroutines::coroutine::push_type sink( // constructor does NOT enter coroutine-function [&](boost::coroutines::coroutine::pull_type& source){ for (int i:source) { std::cout << i << " "; } }); std::vector 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. boost::coroutines::coroutine>::push_type sink( [&](boost::coroutines::coroutine>::pull_type& source){ // access tuple {7,11}; x==7 y==1 int x,y; boost::tie(x,y)=source.get(); }); sink(boost::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. 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 { // code that might throw } catch(const forced_unwind&) { throw; } 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`, indicates whether the destructor should unwind the stack (stack is unwound by default). Stack unwinding assumes the following preconditions: * The coroutine is not __not_a_coro__ * The coroutine is not complete * The coroutine is not running * The coroutine owns a stack After unwinding, a __coro__ is complete. struct X { X(){ std::cout<<"X()"<::push_type sink( [&](boost::coroutines::coroutine::pull_type& source){ X x; for(int=0;;++i){ std::cout<<"fn(): "<::pull_type source( [&]( boost::coroutines::coroutine< int >::push_type & sink){ int counter=0,result=1; while(counter++::push_type sink( [&](boost::coroutines::coroutine::pull_type& source){ while(source){ std::cout << source.get() << " "; source(); } }); std::vector v{1,1,2,3,5,8,13,21,34,55}; std::copy(boost::begin(v),boost::end(v),boost::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 template< typename R > class coroutine<>::pull_type { public: pull_type(); template< typename Fn, typename StackAllocator = stack_allocator, typename Allocator = std::allocator< coroutine > > pull_type( Fn fn, attributes const& attr = attributes(), StackAllocator const& stack_alloc = StackAllocator(), Allocator const& alloc = Allocator() ); template< typename Fn, typename StackAllocator = stack_allocator, typename Allocator = std::allocator< coroutine > > pull_type( Fn && fn, attributes const& attr = attributes(), StackAllocator stack_alloc = StackAllocator(), Allocator const& alloc = Allocator() ); pull_type( pull_type && other); pull_type & operator=( pull_type && other); operator unspecified-bool-type() const; bool operator!() const; void swap( pull_type & other); bool empty() const; pull_type & operator()(); bool has_result() const; R get() const; }; template< typename R > void swap( pull_type< R > & l, pull_type< R > & r); template< typename R > range_iterator< pull_type< R > >::type begin( pull_type< R > &); template< typename R > range_iterator< pull_type< R > >::type end( pull_type< R > &); [heading `pull_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)`] [variablelist [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize() when ! is_stack_unbound().]] [[Effects:] [Creates a coroutine which will execute `fn`. Argument `attr` 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)`] [variablelist [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize() when ! is_stack_unbound().]] [[Effects:] [Creates a coroutine which will execute `fn`. Argument `attr` 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)`] [variablelist [[Effects:] [Moves the internal data of `other` to `*this`. `other` becomes __not_a_coro__.]] [[Throws:] [Nothing.]] ] [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__.]] [[Throws:] [Nothing.]] ] [heading `operator unspecified-bool-type() const`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__ or the coroutine-function has returned (completed), the function returns false. Otherwise true.]] [[Throws:] [Nothing.]] ] [heading `bool operator!() const`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__ or the coroutine-function has returned (completed), the function returns true. Otherwise false.]] [[Throws:] [Nothing.]] ] [heading `bool empty()`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__, the function returns true. Otherwise false.]] [[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 `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.]] ] [heading `R get()()`] R coroutine::pull_type::get(); R& coroutine::pull_type::get(); void coroutinepull_type::get()=delete; [variablelist [[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 R > void swap( pull_type< R > & l, pull_type< R > & 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 > &); [variablelist [[Returns:] [Returns a range-iterator (input-iterator).]] ] [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 (input-iterator).]] ] [endsect] [section:push_coro Class `coroutine<>::push_type`] #include template< typename Arg > class coroutine<>::push_type { public: push_type(); template< typename Fn, typename StackAllocator = stack_allocator, typename Allocator = std::allocator< coroutine > > push_type( Fn fn, attributes const& attr = attributes(), StackAllocator const& stack_alloc = StackAllocator(), Allocator const& alloc = Allocator() ); template< typename Fn, typename StackAllocator = stack_allocator, typename Allocator = std::allocator< coroutine > > push_type( Fn && fn, attributes const& attr = attributes(), StackAllocator stack_alloc = StackAllocator(), Allocator const& alloc = Allocator() ); push_type( push_type && other); push_type & operator=( push_type && other); operator unspecified-bool-type() const; bool operator!() const; void swap( push_type & other); bool empty() const; push_type & operator()( Arg&& arg); }; template< typename Arg > void swap( push_type< Arg > & l, push_type< Arg > & r); template< typename Arg > range_iterator< push_type< Arg > >::type begin( push_type< Arg > &); template< typename Arg > range_iterator< push_type< Arg > >::type end( push_type< Arg > &); [heading `push_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)`] [variablelist [[Preconditions:] [`size` > minimum_stacksize(), `size` < maximum_stacksize() when ! is_stack_unbound().]] [[Effects:] [Creates a coroutine which will execute `fn`. Argument `attr` 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.]] ] [heading `template< typename Fn, typename StackAllocator, typename Allocator > 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().]] [[Effects:] [Creates a coroutine which will execute `fn`. Argument `attr` 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.]] ] [heading `push_type( push_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)`] [variablelist [[Effects:] [Destroys the internal data of `*this` and moves the internal data of `other` to `*this`. `other` becomes __not_a_coro__.]] [[Throws:] [Nothing.]] ] [heading `operator unspecified-bool-type() const`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__ or the coroutine-function has returned (completed), the function returns false. Otherwise true.]] [[Throws:] [Nothing.]] ] [heading `bool operator!() const`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__ or the coroutine-function has returned (completed), the function returns true. Otherwise false.]] [[Throws:] [Nothing.]] ] [heading `bool empty()`] [variablelist [[Returns:] [If `*this` refers to __not_a_coro__, the function returns true. Otherwise false.]] [[Throws:] [Nothing.]] ] [heading `push_type<> & operator()(Arg&& arg)`] push_type& coroutine::push_type::operator()(const Arg&); push_type& coroutine::push_type::operator()(Arg&&); push_type& coroutine::push_type::operator()(Arg&); push_type& coroutine::push_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.]] [[Throws:] [Exceptions thrown inside __coro_fn__.]] ] [heading `void swap( push_type & other)`] [variablelist [[Effects:] [Swaps the internal data from `*this` with the values of `other`.]] [[Throws:] [Nothing.]] ] [heading `T caller_type::operator()( R)`] [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__.]] [[Throws:] [Nothing.]] ] [heading Non-member function `swap()`] 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( push_type< Arg > &)`] template< typename Arg > range_iterator< push_type< Arg > >::type begin( push_type< Arg > &); [variablelist [[Returns:] [Returns a range-iterator (output-iterator).]] ] [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 (output-iterator).]] ] [endsect] [endsect]