ceph/src/boost/libs/coroutine/doc/coroutine.qbk

   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
  11 coroutines.
  12
  13 Symmetric coroutines occur usually in the context of concurrent programming
  14 in order to represent independent units of execution.
  15 Implementations that produce sequences of values typically use asymmetric
  16 coroutines.
  17 [footnote Moura, Ana Lucia De and Ierusalimschy, Roberto.
  18 "Revisiting coroutines". ACM Trans. Program. Lang. Syst., Volume 31 Issue 2,
  19 February 2009, Article No. 6]
  20
  21
  22 [heading stackful]
  23 Each instance of a coroutine has its own stack.
  24
  25 In contrast to stackless coroutines, stackful coroutines allow invoking the
  26 suspend operation out of arbitrary sub-stackframes, enabling escape-and-reenter
  27 recursive operations.
  28
  29
  30 [heading move-only]
  31 A coroutine is moveable-only.
  32
  33 If it were copyable, then its stack with all the objects allocated on it
  34 would be copied too. That would force undefined behaviour if some of these
  35 objects were RAII-classes (manage a resource via RAII pattern). When the first
  36 of the coroutine copies terminates (unwinds its stack), the RAII class
  37 destructors will release their managed resources. When the second copy
  38 terminates, the same destructors will try to doubly-release the same resources,
  39 leading to undefined behaviour.
  40
  41
  42 [heading clean-up]
  43 On coroutine destruction the associated stack will be unwound.
  44
  45 The 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
  54 It is not always possible to accurately estimate the required stack size - in
  55 most cases too much memory is allocated (waste of virtual address-space).
  56
  57 At construction a coroutine starts with a default (minimal) stack size. This
  58 minimal stack size is the maximum of page size and the canonical size for signal
  59 stack (macro SIGSTKSZ on POSIX).
  60
  61 At this time of writing only GCC (4.7)
  62 [footnote [@http://gcc.gnu.org/wiki/SplitStacks Ian Lance Taylor, Split Stacks in GCC]]
  63 is known to support segmented stacks. With version 1.54 __boost_coroutine__
  64 provides support for segmented stacks.
  65
  66 The destructor releases the associated stack. The implementer is free to
  67 deallocate the stack or to cache it for later usage.
  68
  69
  70 [heading context switch]
  71 A coroutine saves and restores registers according to the underlying ABI on
  72 each context switch (using __boost_context__).
  73
  74 Some applications do not use floating-point registers and can disable preserving
  75 FPU registers for performance reasons.
  76
  77 [note According to the calling convention the FPU registers are preserved by
  78 default.]
  79
  80 On POSIX systems, the coroutine context switch does not preserve signal masks
  81 for performance reasons.
  82
  83 A 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
  87 inside the [_same] coroutine results in undefined behaviour.]
  88
  89 As 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]