libs/coroutine/doc/html/coroutine/coroutine.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Coroutine</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Coroutine">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Coroutine">
   9 <link rel="prev" href="motivation.html" title="Motivation">
  10 <link rel="next" href="coroutine/asymmetric.html" title="Asymmetric coroutine">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="motivation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="coroutine/asymmetric.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="coroutine.coroutine"></a><a class="link" href="coroutine.html" title="Coroutine">Coroutine</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="coroutine/asymmetric.html">Asymmetric coroutine</a></span></dt>
  31 <dd><dl>
  32 <dt><span class="section"><a href="coroutine/asymmetric/pull_coro.html">Class <code class="computeroutput"><span class="identifier">asymmetric_coroutine</span><span class="special">&lt;&gt;::</span><span class="identifier">pull_type</span></code></a></span></dt>
  33 <dt><span class="section"><a href="coroutine/asymmetric/push_coro.html">Class <code class="computeroutput"><span class="identifier">asymmetric_coroutine</span><span class="special">&lt;&gt;::</span><span class="identifier">push_type</span></code></a></span></dt>
  34 </dl></dd>
  35 <dt><span class="section"><a href="coroutine/symmetric.html">Symmetric coroutine</a></span></dt>
  36 <dd><dl>
  37 <dt><span class="section"><a href="coroutine/symmetric/symmetric_coro.html">Class
  38         <code class="computeroutput"><span class="identifier">symmetric_coroutine</span><span class="special">&lt;&gt;::</span><span class="identifier">call_type</span></code></a></span></dt>
  39 <dt><span class="section"><a href="coroutine/symmetric/yield_coro.html">Class <code class="computeroutput"><span class="identifier">symmetric_coroutine</span><span class="special">&lt;&gt;::</span><span class="identifier">yield_type</span></code></a></span></dt>
  40 </dl></dd>
  41 </dl></div>
  42 <p>
  43       <span class="bold"><strong>Boost.Coroutine</strong></span> provides two implementations
  44       - asymmetric and symmetric coroutines.
  45     </p>
  46 <p>
  47       Symmetric coroutines occur usually in the context of concurrent programming
  48       in order to represent independent units of execution. Implementations that
  49       produce sequences of values typically use asymmetric coroutines. <a href="#ftn.coroutine.coroutine.f0" class="footnote" name="coroutine.coroutine.f0"><sup class="footnote">[5]</sup></a>
  50     </p>
  51 <h4>
  52 <a name="coroutine.coroutine.h0"></a>
  53       <span class="phrase"><a name="coroutine.coroutine.stackful"></a></span><a class="link" href="coroutine.html#coroutine.coroutine.stackful">stackful</a>
  54     </h4>
  55 <p>
  56       Each instance of a coroutine has its own stack.
  57     </p>
  58 <p>
  59       In contrast to stackless coroutines, stackful coroutines allow invoking the
  60       suspend operation out of arbitrary sub-stackframes, enabling escape-and-reenter
  61       recursive operations.
  62     </p>
  63 <h4>
  64 <a name="coroutine.coroutine.h1"></a>
  65       <span class="phrase"><a name="coroutine.coroutine.move_only"></a></span><a class="link" href="coroutine.html#coroutine.coroutine.move_only">move-only</a>
  66     </h4>
  67 <p>
  68       A coroutine is moveable-only.
  69     </p>
  70 <p>
  71       If it were copyable, then its stack with all the objects allocated on it would
  72       be copied too. That would force undefined behaviour if some of these objects
  73       were RAII-classes (manage a resource via RAII pattern). When the first of the
  74       coroutine copies terminates (unwinds its stack), the RAII class destructors
  75       will release their managed resources. When the second copy terminates, the
  76       same destructors will try to doubly-release the same resources, leading to
  77       undefined behaviour.
  78     </p>
  79 <h4>
  80 <a name="coroutine.coroutine.h2"></a>
  81       <span class="phrase"><a name="coroutine.coroutine.clean_up"></a></span><a class="link" href="coroutine.html#coroutine.coroutine.clean_up">clean-up</a>
  82     </h4>
  83 <p>
  84       On coroutine destruction the associated stack will be unwound.
  85     </p>
  86 <p>
  87       The constructor of coroutine allows you to pass a customized <span class="emphasis"><em>stack-allocator</em></span>.
  88       <span class="emphasis"><em>stack-allocator</em></span> is free to deallocate the stack or cache
  89       it for future usage (for coroutines created later).
  90     </p>
  91 <h4>
  92 <a name="coroutine.coroutine.h3"></a>
  93       <span class="phrase"><a name="coroutine.coroutine.segmented_stack"></a></span><a class="link" href="coroutine.html#coroutine.coroutine.segmented_stack">segmented
  94       stack</a>
  95     </h4>
  96 <p>
  97       <span class="emphasis"><em>symmetric_coroutine&lt;&gt;::call_type</em></span>, <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::push_type</em></span>
  98       and <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::pull_type</em></span> support segmented
  99       stacks (growing on demand).
 100     </p>
 101 <p>
 102       It is not always possible to accurately estimate the required stack size -
 103       in most cases too much memory is allocated (waste of virtual address-space).
 104     </p>
 105 <p>
 106       At construction a coroutine starts with a default (minimal) stack size. This
 107       minimal stack size is the maximum of page size and the canonical size for signal
 108       stack (macro SIGSTKSZ on POSIX).
 109     </p>
 110 <p>
 111       At this time of writing only GCC (4.7) <a href="#ftn.coroutine.coroutine.f1" class="footnote" name="coroutine.coroutine.f1"><sup class="footnote">[6]</sup></a> is known to support segmented stacks. With version 1.54 <span class="bold"><strong>Boost.Coroutine</strong></span> provides support for segmented stacks.
 112     </p>
 113 <p>
 114       The destructor releases the associated stack. The implementer is free to deallocate
 115       the stack or to cache it for later usage.
 116     </p>
 117 <h4>
 118 <a name="coroutine.coroutine.h4"></a>
 119       <span class="phrase"><a name="coroutine.coroutine.context_switch"></a></span><a class="link" href="coroutine.html#coroutine.coroutine.context_switch">context
 120       switch</a>
 121     </h4>
 122 <p>
 123       A coroutine saves and restores registers according to the underlying ABI on
 124       each context switch (using <span class="bold"><strong>Boost.Context</strong></span>).
 125     </p>
 126 <p>
 127       Some applications do not use floating-point registers and can disable preserving
 128       FPU registers for performance reasons.
 129     </p>
 130 <div class="note"><table border="0" summary="Note">
 131 <tr>
 132 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 133 <th align="left">Note</th>
 134 </tr>
 135 <tr><td align="left" valign="top"><p>
 136         According to the calling convention the FPU registers are preserved by default.
 137       </p></td></tr>
 138 </table></div>
 139 <p>
 140       On POSIX systems, the coroutine context switch does not preserve signal masks
 141       for performance reasons.
 142     </p>
 143 <p>
 144       A context switch is done via <span class="emphasis"><em>symmetric_coroutine&lt;&gt;::call_type::operator()</em></span>,
 145       <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::push_type::operator()</em></span> and
 146       <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::pull_type::operator()</em></span>.
 147     </p>
 148 <div class="warning"><table border="0" summary="Warning">
 149 <tr>
 150 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
 151 <th align="left">Warning</th>
 152 </tr>
 153 <tr><td align="left" valign="top"><p>
 154         Calling <span class="emphasis"><em>symmetric_coroutine&lt;&gt;::call_type::operator()</em></span>,
 155         <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::push_type::operator()</em></span>
 156         and <span class="emphasis"><em>asymmetric_coroutine&lt;&gt;::pull_type::operator()</em></span>
 157         from inside the <span class="underline">same</span> coroutine results
 158         in undefined behaviour.
 159       </p></td></tr>
 160 </table></div>
 161 <p>
 162       As an example, the code below will result in undefined behaviour:
 163     </p>
 164 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">coroutines</span><span class="special">::</span><span class="identifier">symmetric_coroutine</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;::</span><span class="identifier">call_type</span> <span class="identifier">coro</span><span class="special">(</span>
 165     <span class="special">[&amp;](</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">coroutines</span><span class="special">::</span><span class="identifier">symmetric_coroutine</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;::</span><span class="identifier">yield_type</span><span class="special">&amp;</span> <span class="identifier">yield</span><span class="special">){</span>
 166         <span class="identifier">yield</span><span class="special">(</span><span class="identifier">coro</span><span class="special">);</span> <span class="comment">// yield to same symmetric_coroutine</span>
 167 <span class="special">});</span>
 168 <span class="identifier">coro</span><span class="special">();</span>
 169 </pre>
 170 <div class="footnotes">
 171 <br><hr style="width:100; text-align:left;margin-left: 0">
 172 <div id="ftn.coroutine.coroutine.f0" class="footnote"><p><a href="#coroutine.coroutine.f0" class="para"><sup class="para">[5] </sup></a>
 173         Moura, Ana Lucia De and Ierusalimschy, Roberto. "Revisiting coroutines".
 174         ACM Trans. Program. Lang. Syst., Volume 31 Issue 2, February 2009, Article
 175         No. 6
 176       </p></div>
 177 <div id="ftn.coroutine.coroutine.f1" class="footnote"><p><a href="#coroutine.coroutine.f1" class="para"><sup class="para">[6] </sup></a>
 178         <a href="http://gcc.gnu.org/wiki/SplitStacks" target="_top">Ian Lance Taylor, Split
 179         Stacks in GCC</a>
 180       </p></div>
 181 </div>
 182 </div>
 183 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 184 <td align="left"></td>
 185 <td align="right"><div class="copyright-footer">Copyright &#169; 2009 Oliver Kowalke<p>
 186         Distributed under the Boost Software License, Version 1.0. (See accompanying
 187         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 188       </p>
 189 </div></td>
 190 </tr></table>
 191 <hr>
 192 <div class="spirit-nav">
 193 <a accesskey="p" href="motivation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="coroutine/asymmetric.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 194 </div>
 195 </body>
 196 </html>