1[/ 2 Copyright Oliver Kowalke 2009. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt 6] 7 8[section:coroutine Coroutine] 9 10__boost_coroutine__ provides two implementations - asymmetric and symmetric 11coroutines. 12 13Symmetric coroutines occur usually in the context of concurrent programming 14in order to represent independent units of execution. 15Implementations that produce sequences of values typically use asymmetric 16coroutines. 17[footnote Moura, Ana Lucia De and Ierusalimschy, Roberto. 18"Revisiting coroutines". ACM Trans. Program. Lang. Syst., Volume 31 Issue 2, 19February 2009, Article No. 6] 20 21 22[heading stackful] 23Each instance of a coroutine has its own stack. 24 25In contrast to stackless coroutines, stackful coroutines allow invoking the 26suspend operation out of arbitrary sub-stackframes, enabling escape-and-reenter 27recursive operations. 28 29 30[heading move-only] 31A coroutine is moveable-only. 32 33If it were copyable, then its stack with all the objects allocated on it 34would be copied too. That would force undefined behaviour if some of these 35objects were RAII-classes (manage a resource via RAII pattern). When the first 36of the coroutine copies terminates (unwinds its stack), the RAII class 37destructors will release their managed resources. When the second copy 38terminates, the same destructors will try to doubly-release the same resources, 39leading to undefined behaviour. 40 41 42[heading clean-up] 43On coroutine destruction the associated stack will be unwound. 44 45The constructor of coroutine allows you to pass a customized ['stack-allocator]. 46['stack-allocator] is free to deallocate the stack or cache it for future usage 47(for coroutines created later). 48 49 50[heading segmented stack] 51__call_coro__, __push_coro__ and __pull_coro__ support segmented stacks 52(growing on demand). 53 54It is not always possible to accurately estimate the required stack size - in 55most cases too much memory is allocated (waste of virtual address-space). 56 57At construction a coroutine starts with a default (minimal) stack size. This 58minimal stack size is the maximum of page size and the canonical size for signal 59stack (macro SIGSTKSZ on POSIX). 60 61At this time of writing only GCC (4.7) 62[footnote [@http://gcc.gnu.org/wiki/SplitStacks Ian Lance Taylor, Split Stacks in GCC]] 63is known to support segmented stacks. With version 1.54 __boost_coroutine__ 64provides support for segmented stacks. 65 66The destructor releases the associated stack. The implementer is free to 67deallocate the stack or to cache it for later usage. 68 69 70[heading context switch] 71A coroutine saves and restores registers according to the underlying ABI on 72each context switch (using __boost_context__). 73 74Some applications do not use floating-point registers and can disable preserving 75FPU registers for performance reasons. 76 77[note According to the calling convention the FPU registers are preserved by 78default.] 79 80On POSIX systems, the coroutine context switch does not preserve signal masks 81for performance reasons. 82 83A context switch is done via __call_coro_op__, __push_coro_op__ and 84__pull_coro_op__. 85 86[warning Calling __call_coro_op__, __push_coro_op__ and __pull_coro_op__ from 87inside the [_same] coroutine results in undefined behaviour.] 88 89As an example, the code below will result in undefined behaviour: 90 91 boost::coroutines::symmetric_coroutine<void>::call_type coro( 92 [&](boost::coroutines::symmetric_coroutine<void>::yield_type& yield){ 93 yield(coro); // yield to same symmetric_coroutine 94 }); 95 coro(); 96 97 98[include asymmetric.qbk] 99[include symmetric.qbk] 100 101[endsect] 102