boost/context
2
0
Fork 0
mirror of https://github.com/boostorg/context.git synced 2026-01-22 05:02:16 +00:00
Code Issues Projects Releases Wiki Activity
Files
olk-patch-1
context/doc/html/context/fib.html
Tianqi 28b86c9c6b fix typos in doc
2021-03-10 21:19:58 +08:00

513 lines
54 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Context switching with fibers</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Context">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Context">
<link rel="prev" href="requirements.html" title="Requirements">
<link rel="next" href="fib/implementations__fcontext_t__ucontext_t_and_winfiber.html" title="Implementations: fcontext_t, ucontext_t and WinFiber">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="requirements.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="fib/implementations__fcontext_t__ucontext_t_and_winfiber.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="context.fib"></a><a name="fib"></a><a class="link" href="fib.html" title="Context switching with fibers">Context switching with fibers</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="fib/implementations__fcontext_t__ucontext_t_and_winfiber.html">Implementations:
fcontext_t, ucontext_t and WinFiber</a></span></dt>
<dt><span class="section"><a href="fib/class__fiber_.html">Class <code class="computeroutput"><span class="identifier">fiber</span></code></a></span></dt>
</dl></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
__fiber__ is the reference implementation of C++ proposal <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0534r3.pdf" target="_top">P0876R0:
fibers without scheduler</a>.
</p></td></tr>
</table></div>
<p>
A fiber represents the state of the control flow of a program at a given point
in time. Fibers can be suspended and resumed later in order to change the control
flow of a program.
</p>
<p>
Modern micro-processors are registers machines; the content of processor registers
represent a fiber of the executed program at a given point in time. Operating
systems simulate parallel execution of programs on a single processor by switching
between programs (context switch) by preserving and restoring the fiber, e.g.
the content of all registers.
</p>
<h4>
<a name="context.fib.h0"></a>
<span><a name="context.fib.__fiber__"></a></span><a class="link" href="fib.html#context.fib.__fiber__">__fiber__</a>
</h4>
<p>
__fiber__ captures the current fiber (the rest of the computation; code after
__fiber__) and triggers a context switch. The context switch is achieved by
preserving certain registers (including instruction and stack pointer), defined
by the calling convention of the ABI, of the current fiber and restoring those
registers of the resumed fiber. The control flow of the resumed fiber continues.
The current fiber is suspended and passed as argument to the resumed fiber.
</p>
<p>
__fiber__ expects a <span class="emphasis"><em>context-function</em></span> with signature <code class="computeroutput"><span class="char">'fiber(fiber &amp;&amp; f)'</span></code>. The parameter <code class="computeroutput"><span class="identifier">f</span></code> represents the current fiber from which
this fiber was resumed (e.g. that has called __fiber__).
</p>
<p>
On return the <span class="emphasis"><em>context-function</em></span> of the current fiber has
to specify an <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a> to
which the execution control is transferred after termination of the current
fiber.
</p>
<p>
If an instance with valid state goes out of scope and the <span class="emphasis"><em>context-function</em></span>
has not yet returned, the stack is traversed in order to access the control
structure (address stored at the first stack frame) and fiber's stack is deallocated
via the <span class="emphasis"><em>StackAllocator</em></span>.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
<a class="link" href="stack/segmented.html#segmented"><span class="emphasis"><em>Segmented stacks</em></span></a> are
supported by __fiber__ using <a class="link" href="fib/implementations__fcontext_t__ucontext_t_and_winfiber.html#implementation"><span class="emphasis"><em>ucontext_t</em></span></a>.
</p></td></tr>
</table></div>
<p>
<a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a> represents a fiber;
it contains the content of preserved registers and manages the associated stack
(allocation/deallocation). <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a>
is a one-shot fiber - it can be used only once, after calling <span class="emphasis"><em>continuation::resume()</em></span>
or <span class="emphasis"><em>continuation::resume_with()</em></span> it is invalidated.
</p>
<p>
<a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a> is only move-constructible
and move-assignable.
</p>
<p>
As a first-class object <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a>
can be applied to and returned from a function, assigned to a variable or stored
in a container.
</p>
<p>
A fiber is continued by calling <code class="computeroutput"><span class="identifier">resume</span><span class="special">()</span></code>/<code class="computeroutput"><span class="identifier">resume_with</span><span class="special">()</span></code>.
</p>
<h4>
<a name="context.fib.h1"></a>
<span><a name="context.fib.usage"></a></span><a class="link" href="fib.html#context.fib.usage">Usage</a>
</h4>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">a</span><span class="special">;</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">source</span><span class="special">{[&amp;</span><span class="identifier">a</span><span class="special">](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">sink</span><span class="special">){</span>
<span class="identifier">a</span><span class="special">=</span><span class="number">0</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">b</span><span class="special">=</span><span class="number">1</span><span class="special">;</span>
<span class="keyword">for</span><span class="special">(;;){</span>
<span class="identifier">sink</span><span class="special">=</span><span class="identifier">sink</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="keyword">int</span> <span class="identifier">next</span><span class="special">=</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">;</span>
<span class="identifier">a</span><span class="special">=</span><span class="identifier">b</span><span class="special">;</span>
<span class="identifier">b</span><span class="special">=</span><span class="identifier">next</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>
<span class="special">}};</span>
<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">j</span><span class="special">=</span><span class="number">0</span><span class="special">;</span><span class="identifier">j</span><span class="special">&lt;</span><span class="number">10</span><span class="special">;++</span><span class="identifier">j</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">source</span><span class="special">=</span><span class="identifier">source</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
<span class="special">}</span>
<span class="identifier">output</span><span class="special">:</span>
<span class="number">0</span> <span class="number">1</span> <span class="number">1</span> <span class="number">2</span> <span class="number">3</span> <span class="number">5</span> <span class="number">8</span> <span class="number">13</span> <span class="number">21</span> <span class="number">34</span>
</pre>
<p>
This simple example demonstrates the basic usage of __fiber__ as a <span class="emphasis"><em>generator</em></span>.
The fiber <code class="computeroutput"><span class="identifier">sink</span></code> represents the
<span class="emphasis"><em>main</em></span>-fiber (function <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>). <code class="computeroutput"><span class="identifier">sink</span></code>
is captured (current-fiber) by invoking __fiber__ and passed as parameter to
the lambda.
</p>
<p>
Because the state is invalidated (one-shot fiber) by each call of <span class="emphasis"><em>continuation::resume()</em></span>,
the new state of the <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a>,
returned by <span class="emphasis"><em>continuation::resume()</em></span>, needs to be assigned
to <code class="computeroutput"><span class="identifier">sink</span></code> after each call.
</p>
<p>
The lambda that calculates the Fibonacci numbers is executed inside the fiber
represented by <code class="computeroutput"><span class="identifier">source</span></code>. Calculated
Fibonacci numbers are transferred between the two fibers via variable <code class="computeroutput"><span class="identifier">a</span></code> (lambda capture reference).
</p>
<p>
The locale variables <code class="computeroutput"><span class="identifier">b</span></code> and
<code class="computeroutput"> <span class="identifier">next</span></code> remain their values during
each context switch. This is possible due <code class="computeroutput"><span class="identifier">source</span></code>
has its own stack and the stack is exchanged by each context switch.
</p>
<h4>
<a name="context.fib.h2"></a>
<span><a name="context.fib.parameter_passing"></a></span><a class="link" href="fib.html#context.fib.parameter_passing">Parameter
passing</a>
</h4>
<p>
Data can be transferred between two fibers via global pointers, calling wrappers
(like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind</span></code>) or lambda captures.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">i</span><span class="special">=</span><span class="number">1</span><span class="special">;</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f1</span><span class="special">{[&amp;</span><span class="identifier">i</span><span class="special">](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f2</span><span class="special">){</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span><span class="special">(</span><span class="string">"inside f1,i==%d\n"</span><span class="special">,</span><span class="identifier">i</span><span class="special">);</span>
<span class="identifier">i</span><span class="special">+=</span><span class="number">1</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">f2</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="special">}};</span>
<span class="identifier">f1</span><span class="special">=</span><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span><span class="special">(</span><span class="string">"i==%d\n"</span><span class="special">,</span><span class="identifier">i</span><span class="special">);</span>
<span class="identifier">output</span><span class="special">:</span>
<span class="identifier">inside</span> <span class="identifier">c1</span><span class="special">,</span><span class="identifier">i</span><span class="special">==</span><span class="number">1</span>
<span class="identifier">i</span><span class="special">==</span><span class="number">2</span>
</pre>
<p>
<code class="computeroutput"><span class="identifier">callcc</span><span class="special">(&lt;</span><span class="identifier">lambda</span><span class="special">&gt;)</span></code>
enters the lambda in fiber represented by <code class="computeroutput"><span class="identifier">c1</span></code>
with lambda capture reference <code class="computeroutput"><span class="identifier">i</span><span class="special">=</span><span class="number">1</span></code>. The expression
<code class="computeroutput"><span class="identifier">c2</span><span class="special">.</span><span class="identifier">resume</span><span class="special">()</span></code>
resumes the fiber <code class="computeroutput"><span class="identifier">c2</span></code>. On return
of <code class="computeroutput"><span class="identifier">callcc</span><span class="special">(&lt;</span><span class="identifier">lambda</span><span class="special">&gt;)</span></code>,
the variable <code class="computeroutput"><span class="identifier">i</span></code> has the value
of <code class="computeroutput"><span class="identifier">i</span><span class="special">+</span><span class="number">1</span></code>.
</p>
<h4>
<a name="context.fib.h3"></a>
<span><a name="context.fib.exception_handling"></a></span><a class="link" href="fib.html#context.fib.exception_handling">Exception
handling</a>
</h4>
<p>
If the function executed inside a <span class="emphasis"><em>context-function</em></span> emits
an exception, the application is terminated by calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span><span class="special">()</span></code>. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception_ptr</span></code>
can be used to transfer exceptions between different fibers.
</p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
Do not jump from inside a catch block and then re-throw the exception in
another fiber.
</p></td></tr>
</table></div>
<a name="cc_ontop"></a><h4>
<a name="context.fib.h4"></a>
<span><a name="context.fib.executing_function_on_top_of_a_fiber"></a></span><a class="link" href="fib.html#context.fib.executing_function_on_top_of_a_fiber">Executing
function on top of a fiber</a>
</h4>
<p>
Sometimes it is useful to execute a new function on top of a resumed fiber.
For this purpose <span class="emphasis"><em>continuation::resume_with()</em></span> has to be
used. The function passed as argument must accept a rvalue reference to <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a> and return <code class="computeroutput"><span class="keyword">void</span></code>.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">data</span><span class="special">=</span><span class="number">0</span><span class="special">;</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f1</span><span class="special">{[&amp;</span><span class="identifier">data</span><span class="special">](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f2</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: entered first time: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">+=</span><span class="number">1</span><span class="special">;</span>
<span class="identifier">f2</span><span class="special">=</span><span class="identifier">f2</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: entered second time: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">+=</span><span class="number">1</span><span class="special">;</span>
<span class="identifier">f2</span><span class="special">=</span><span class="identifier">f2</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: entered third time: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f2</span><span class="special">);</span>
<span class="special">}};</span>
<span class="identifier">f1</span><span class="special">=</span><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: returned first time: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">+=</span><span class="number">1</span><span class="special">;</span>
<span class="identifier">f1</span><span class="special">=</span><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: returned second time: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">+=</span><span class="number">1</span><span class="special">;</span>
<span class="identifier">f1</span><span class="special">=</span><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume_with</span><span class="special">([&amp;</span><span class="identifier">data</span><span class="special">](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f2</span><span class="special">){</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f2: entered: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">=-</span><span class="number">1</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span> <span class="identifier">f2</span><span class="special">);</span>
<span class="special">});</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"f1: returned third time"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">output</span><span class="special">:</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">entered</span> <span class="identifier">first</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">0</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">returned</span> <span class="identifier">first</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">entered</span> <span class="identifier">second</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">2</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">returned</span> <span class="identifier">second</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">3</span>
<span class="identifier">f2</span><span class="special">:</span> <span class="identifier">entered</span><span class="special">:</span> <span class="number">4</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">entered</span> <span class="identifier">third</span> <span class="identifier">time</span><span class="special">:</span> <span class="special">-</span><span class="number">1</span>
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">returned</span> <span class="identifier">third</span> <span class="identifier">time</span>
</pre>
<p>
The expression <code class="computeroutput"><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume_with</span><span class="special">(...)</span></code>
executes a lambda on top of fiber <code class="computeroutput"><span class="identifier">f1</span></code>,
e.g. an additional stack frame is allocated on top of the stack. This lambda
assigns <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>
to <code class="computeroutput"><span class="identifier">data</span></code> and returns to the
second invocation of <code class="computeroutput"><span class="identifier">f1</span><span class="special">.</span><span class="identifier">resume</span><span class="special">()</span></code>.
</p>
<p>
Another option is to execute a function on top of the fiber that throws an
exception.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="keyword">struct</span> <span class="identifier">my_exception</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">{</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">;</span>
<span class="identifier">my_exception</span><span class="special">(</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f_</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">what</span><span class="special">)</span> <span class="special">:</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">{</span> <span class="identifier">what</span> <span class="special">},</span>
<span class="identifier">f</span><span class="special">{</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span> <span class="identifier">f_</span><span class="special">)</span> <span class="special">}</span> <span class="special">{</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">{[](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f</span><span class="special">)</span> <span class="special">-&gt;</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"entered"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">try</span> <span class="special">{</span>
<span class="identifier">f</span><span class="special">=</span><span class="identifier">f</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="special">}</span> <span class="keyword">catch</span> <span class="special">(</span><span class="identifier">my_exception</span> <span class="special">&amp;</span> <span class="identifier">ex</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"my_exception: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">ex</span><span class="special">.</span><span class="identifier">f</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="special">{};</span>
<span class="special">});</span>
<span class="identifier">f</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="identifier">f</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">resume_with</span><span class="special">([](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">f</span><span class="special">)</span> <span class="special">-&gt;</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">{</span>
<span class="keyword">throw</span> <span class="identifier">my_exception</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f</span><span class="special">),</span><span class="string">"abc"</span><span class="special">);</span>
<span class="keyword">return</span> <span class="special">{};</span>
<span class="special">});</span>
<span class="identifier">output</span><span class="special">:</span>
<span class="identifier">entered</span>
<span class="identifier">my_exception</span><span class="special">:</span> <span class="identifier">abc</span>
</pre>
<p>
In this exception <code class="computeroutput"><span class="identifier">my_exception</span></code>
is throw from a function invoked on-top of fiber <code class="computeroutput"><span class="identifier">c</span></code>
and catched inside the <code class="computeroutput"><span class="keyword">for</span></code>-loop.
</p>
<h4>
<a name="context.fib.h5"></a>
<span><a name="context.fib.stack_unwinding"></a></span><a class="link" href="fib.html#context.fib.stack_unwinding">Stack
unwinding</a>
</h4>
<p>
On construction of <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a>
a stack is allocated. If the <span class="emphasis"><em>context-function</em></span> returns
the stack will be destructed. If the <span class="emphasis"><em>context-function</em></span>
has not yet returned and the destructor of an valid <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a>
instance (e.g. <span class="emphasis"><em>fiber::operator bool()</em></span> returns <code class="computeroutput"><span class="keyword">true</span></code>) is called, the stack will be destructed
too.
</p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
Code executed by <span class="emphasis"><em>context-function</em></span> must not prevent the
propagation ofs the <span class="emphasis"><em>detail::forced_unwind</em></span> exception.
Absorbing that exception will cause stack unwinding to fail. Thus, any code
that catches all exceptions must re-throw any pending <span class="emphasis"><em>detail::forced_unwind</em></span>
exception.
</p></td></tr>
</table></div>
<a name="cc_prealloc"></a><h4>
<a name="context.fib.h6"></a>
<span><a name="context.fib.allocating_control_structures_on_top_of_stack"></a></span><a class="link" href="fib.html#context.fib.allocating_control_structures_on_top_of_stack">Allocating
control structures on top of stack</a>
</h4>
<p>
Allocating control structures on top of the stack requires to allocated the
<span class="emphasis"><em>stack_context</em></span> and create the control structure with placement
new before <a class="link" href="cc.html#cc"><span class="emphasis"><em>continuation</em></span></a> is created.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
The user is responsible for destructing the control structure at the top
of the stack.
</p></td></tr>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="comment">// stack-allocator used for (de-)allocating stack</span>
<span class="identifier">fixedsize_stack</span> <span class="identifier">salloc</span><span class="special">(</span><span class="number">4048</span><span class="special">);</span>
<span class="comment">// allocate stack space</span>
<span class="identifier">stack_context</span> <span class="identifier">sctx</span><span class="special">(</span><span class="identifier">salloc</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">());</span>
<span class="comment">// reserve space for control structure on top of the stack</span>
<span class="keyword">void</span> <span class="special">*</span> <span class="identifier">sp</span><span class="special">=</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span><span class="special">)-</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">my_control_structure</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">=</span><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">-</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">my_control_structure</span><span class="special">);</span>
<span class="comment">// placement new creates control structure on reserved space</span>
<span class="identifier">my_control_structure</span> <span class="special">*</span> <span class="identifier">cs</span><span class="special">=</span><span class="keyword">new</span><span class="special">(</span><span class="identifier">sp</span><span class="special">)</span><span class="identifier">my_control_structure</span><span class="special">(</span><span class="identifier">sp</span><span class="special">,</span><span class="identifier">size</span><span class="special">,</span><span class="identifier">sctx</span><span class="special">,</span><span class="identifier">salloc</span><span class="special">);</span>
<span class="special">...</span>
<span class="comment">// destructing the control structure</span>
<span class="identifier">cs</span><span class="special">-&gt;~</span><span class="identifier">my_control_structure</span><span class="special">();</span>
<span class="special">...</span>
<span class="keyword">struct</span> <span class="identifier">my_control_structure</span> <span class="special">{</span>
<span class="comment">// captured fiber</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">StackAllocator</span> <span class="special">&gt;</span>
<span class="identifier">my_control_structure</span><span class="special">(</span><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">sp</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span><span class="identifier">stack_context</span> <span class="identifier">sctx</span><span class="special">,</span><span class="identifier">StackAllocator</span> <span class="identifier">salloc</span><span class="special">)</span> <span class="special">:</span>
<span class="comment">// create captured fiber</span>
<span class="identifier">f</span><span class="special">{</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_arg</span><span class="special">,</span><span class="identifier">preallocated</span><span class="special">(</span><span class="identifier">sp</span><span class="special">,</span><span class="identifier">size</span><span class="special">,</span><span class="identifier">sctx</span><span class="special">),</span><span class="identifier">salloc</span><span class="special">,</span><span class="identifier">entry_func</span><span class="special">}</span> <span class="special">{</span>
<span class="special">}</span>
<span class="special">...</span>
<span class="special">};</span>
</pre>
<h4>
<a name="context.fib.h7"></a>
<span><a name="context.fib.inverting_the_control_flow"></a></span><a class="link" href="fib.html#context.fib.inverting_the_control_flow">Inverting
the control flow</a>
</h4>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
<span class="comment">/*
* grammar:
* P ---&gt; E '\0'
* E ---&gt; T {('+'|'-') T}
* T ---&gt; S {('*'|'/') S}
* S ---&gt; digit | '(' E ')'
*/</span>
<span class="keyword">class</span> <span class="identifier">Parser</span><span class="special">{</span>
<span class="keyword">char</span> <span class="identifier">next</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&amp;</span> <span class="identifier">is</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">function</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">(</span><span class="keyword">char</span><span class="special">)&gt;</span> <span class="identifier">cb</span><span class="special">;</span>
<span class="keyword">char</span> <span class="identifier">pull</span><span class="special">(){</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">char_traits</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;::</span><span class="identifier">to_char_type</span><span class="special">(</span><span class="identifier">is</span><span class="special">.</span><span class="identifier">get</span><span class="special">());</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">scan</span><span class="special">(){</span>
<span class="keyword">do</span><span class="special">{</span>
<span class="identifier">next</span><span class="special">=</span><span class="identifier">pull</span><span class="special">();</span>
<span class="special">}</span>
<span class="keyword">while</span><span class="special">(</span><span class="identifier">isspace</span><span class="special">(</span><span class="identifier">next</span><span class="special">));</span>
<span class="special">}</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">Parser</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&amp;</span> <span class="identifier">is_</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">function</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">(</span><span class="keyword">char</span><span class="special">)&gt;</span> <span class="identifier">cb_</span><span class="special">)</span> <span class="special">:</span>
<span class="identifier">next</span><span class="special">(),</span> <span class="identifier">is</span><span class="special">(</span><span class="identifier">is_</span><span class="special">),</span> <span class="identifier">cb</span><span class="special">(</span><span class="identifier">cb_</span><span class="special">)</span>
<span class="special">{}</span>
<span class="keyword">void</span> <span class="identifier">run</span><span class="special">()</span> <span class="special">{</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="identifier">E</span><span class="special">();</span>
<span class="special">}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="keyword">void</span> <span class="identifier">E</span><span class="special">(){</span>
<span class="identifier">T</span><span class="special">();</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">next</span><span class="special">==</span><span class="char">'+'</span><span class="special">||</span><span class="identifier">next</span><span class="special">==</span><span class="char">'-'</span><span class="special">){</span>
<span class="identifier">cb</span><span class="special">(</span><span class="identifier">next</span><span class="special">);</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="identifier">T</span><span class="special">();</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">T</span><span class="special">(){</span>
<span class="identifier">S</span><span class="special">();</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">next</span><span class="special">==</span><span class="char">'*'</span><span class="special">||</span><span class="identifier">next</span><span class="special">==</span><span class="char">'/'</span><span class="special">){</span>
<span class="identifier">cb</span><span class="special">(</span><span class="identifier">next</span><span class="special">);</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="identifier">S</span><span class="special">();</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">S</span><span class="special">(){</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">isdigit</span><span class="special">(</span><span class="identifier">next</span><span class="special">)){</span>
<span class="identifier">cb</span><span class="special">(</span><span class="identifier">next</span><span class="special">);</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="special">}</span>
<span class="keyword">else</span> <span class="keyword">if</span><span class="special">(</span><span class="identifier">next</span><span class="special">==</span><span class="char">'('</span><span class="special">){</span>
<span class="identifier">cb</span><span class="special">(</span><span class="identifier">next</span><span class="special">);</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="identifier">E</span><span class="special">();</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">next</span><span class="special">==</span><span class="char">')'</span><span class="special">){</span>
<span class="identifier">cb</span><span class="special">(</span><span class="identifier">next</span><span class="special">);</span>
<span class="identifier">scan</span><span class="special">();</span>
<span class="special">}</span><span class="keyword">else</span><span class="special">{</span>
<span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span><span class="string">"parsing failed"</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="keyword">else</span><span class="special">{</span>
<span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span><span class="string">"parsing failed"</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">istringstream</span> <span class="identifier">is</span><span class="special">(</span><span class="string">"1+1"</span><span class="special">);</span>
<span class="comment">// user-code pulls parsed data from parser</span>
<span class="comment">// invert control flow</span>
<span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="identifier">done</span><span class="special">=</span><span class="keyword">false</span><span class="special">;</span>
<span class="comment">// execute parser in new fiber</span>
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">source</span><span class="special">{[&amp;</span><span class="identifier">is</span><span class="special">,&amp;</span><span class="identifier">c</span><span class="special">,&amp;</span><span class="identifier">done</span><span class="special">](</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fiber</span> <span class="special">&amp;&amp;</span> <span class="identifier">sink</span><span class="special">){</span>
<span class="comment">// create parser with callback function</span>
<span class="identifier">Parser</span> <span class="identifier">p</span><span class="special">(</span><span class="identifier">is</span><span class="special">,</span>
<span class="special">[&amp;</span><span class="identifier">sink</span><span class="special">,&amp;</span><span class="identifier">c</span><span class="special">](</span><span class="keyword">char</span> <span class="identifier">c_</span><span class="special">){</span>
<span class="comment">// resume main fiber</span>
<span class="identifier">c</span><span class="special">=</span><span class="identifier">c_</span><span class="special">;</span>
<span class="identifier">sink</span><span class="special">=</span><span class="identifier">sink</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="special">});</span>
<span class="comment">// start recursive parsing</span>
<span class="identifier">p</span><span class="special">.</span><span class="identifier">run</span><span class="special">();</span>
<span class="comment">// signal termination</span>
<span class="identifier">done</span><span class="special">=</span><span class="keyword">true</span><span class="special">;</span>
<span class="comment">// resume main fiber</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>
<span class="special">}};</span>
<span class="identifier">source</span> <span class="special">=</span> <span class="identifier">source</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="keyword">while</span><span class="special">(!</span><span class="identifier">done</span><span class="special">){</span>
<span class="identifier">printf</span><span class="special">(</span><span class="string">"Parsed: %c\n"</span><span class="special">,</span><span class="identifier">c</span><span class="special">);</span>
<span class="identifier">source</span><span class="special">=</span><span class="identifier">source</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span>
<span class="special">}</span>
<span class="identifier">output</span><span class="special">:</span>
<span class="identifier">Parsed</span><span class="special">:</span> <span class="number">1</span>
<span class="identifier">Parsed</span><span class="special">:</span> <span class="special">+</span>
<span class="identifier">Parsed</span><span class="special">:</span> <span class="number">1</span>
</pre>
<p>
In this example a recursive descent parser uses a callback to emit a newly
passed symbol. Using __fiber__ the control flow can be inverted, e.g. the user-code
pulls parsed symbols from the parser - instead to get pushed from the parser
(via callback).
</p>
<p>
The data (character) is transferred between the two fibers.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2014 Oliver Kowalke<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="requirements.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="fib/implementations__fcontext_t__ucontext_t_and_winfiber.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink