update docu

This commit is contained in:
Oliver Kowalke 2016-02-10 21:47:27 +01:00
parent e2c93a84f4
commit 1b89400e23
4 changed files with 166 additions and 3 deletions

View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library id="context" name="Context" dirname="context" last-revision="$Date: 2016/02/10 20:01:07 $"
<library id="context" name="Context" dirname="context" last-revision="$Date: 2016/02/10 20:47:12 $"
xmlns:xi="http://www.w3.org/2001/XInclude">
<libraryinfo>
<authorgroup>
@ -559,6 +559,67 @@
<phrase role="identifier">f2</phrase><phrase role="special">:</phrase> <phrase role="identifier">entered</phrase><phrase role="special">:</phrase> <phrase role="number">5</phrase>
<phrase role="identifier">f1</phrase><phrase role="special">:</phrase> <phrase role="identifier">entered</phrase> <phrase role="identifier">third</phrase> <phrase role="identifier">time</phrase><phrase role="special">:</phrase> <phrase role="special">-</phrase><phrase role="number">1</phrase>
</programlisting>
<para>
The expression <code><phrase role="identifier">ctx</phrase><phrase role="special">(</phrase><phrase
role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">exec_ontop_arg</phrase><phrase
role="special">,</phrase><phrase role="identifier">f2</phrase><phrase role="special">,</phrase><phrase
role="identifier">data</phrase><phrase role="special">+</phrase><phrase role="number">1</phrase><phrase
role="special">)</phrase></code> executes <code><phrase role="identifier">f2</phrase><phrase
role="special">()</phrase></code> on top of context <code><phrase role="identifier">ctx</phrase></code>,
e.g. an additional stack frame is allocated on top of the context stack (in
front of <code><phrase role="identifier">f1</phrase><phrase role="special">()</phrase></code>).
<code><phrase role="identifier">f1</phrase><phrase role="special">()</phrase></code>
returns argument <code><phrase role="special">-</phrase><phrase role="number">1</phrase></code>
that will returned by the second invocation of <code><phrase role="identifier">ctx</phrase><phrase
role="special">(</phrase><phrase role="identifier">data</phrase><phrase role="special">+</phrase><phrase
role="number">1</phrase><phrase role="special">)</phrase></code> in <code><phrase
role="identifier">f1</phrase><phrase role="special">()</phrase></code>.
</para>
<para>
Another option is to execute a function on top of the context, that throws
an exception.
</para>
<programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">interrupt</phrase> <phrase role="special">{</phrase>
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase> <phrase role="keyword">void</phrase> <phrase role="special">&gt;</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">;</phrase>
<phrase role="identifier">interrupt</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase> <phrase role="keyword">void</phrase> <phrase role="special">&gt;</phrase> <phrase role="special">&amp;&amp;</phrase> <phrase role="identifier">ctx_</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special">&lt;</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase> <phrase role="keyword">void</phrase> <phrase role="special">&gt;</phrase> <phrase role="special">&gt;(</phrase> <phrase role="identifier">ctx_</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase>
<phrase role="special">}</phrase>
<phrase role="special">};</phrase>
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase><phrase role="keyword">void</phrase><phrase role="special">&gt;</phrase> <phrase role="identifier">f1</phrase><phrase role="special">(</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase><phrase role="keyword">void</phrase><phrase role="special">&gt;</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
<phrase role="keyword">try</phrase> <phrase role="special">{</phrase>
<phrase role="keyword">for</phrase> <phrase role="special">(;;)</phrase> <phrase role="special">{</phrase>
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;f1()&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">();</phrase>
<phrase role="special">}</phrase>
<phrase role="special">}</phrase> <phrase role="keyword">catch</phrase> <phrase role="special">(</phrase><phrase role="identifier">interrupt</phrase> <phrase role="special">&amp;</phrase> <phrase role="identifier">e</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;f1(): interrupted&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">e</phrase><phrase role="special">.</phrase><phrase role="identifier">ctx</phrase><phrase role="special">);</phrase>
<phrase role="special">}</phrase>
<phrase role="keyword">return</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase>
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase><phrase role="keyword">void</phrase><phrase role="special">&gt;</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase><phrase role="keyword">void</phrase><phrase role="special">&gt;</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
<phrase role="keyword">throw</phrase> <phrase role="identifier">interrupt</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase><phrase role="identifier">ctx</phrase><phrase role="special">));</phrase>
<phrase role="keyword">return</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase>
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">&lt;</phrase> <phrase role="keyword">void</phrase> <phrase role="special">&gt;</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">(</phrase><phrase role="identifier">f1</phrase><phrase role="special">);</phrase>
<phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">();</phrase>
<phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">();</phrase>
<phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">(</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">exec_ontop_arg</phrase><phrase role="special">,</phrase><phrase role="identifier">f2</phrase><phrase role="special">);</phrase>
<phrase role="identifier">output</phrase><phrase role="special">:</phrase>
<phrase role="identifier">f1</phrase><phrase role="special">()</phrase>
<phrase role="identifier">f1</phrase><phrase role="special">()</phrase>
<phrase role="identifier">f1</phrase><phrase role="special">():</phrase> <phrase role="identifier">interrupted</phrase>
</programlisting>
<para>
In this example <code><phrase role="identifier">f2</phrase><phrase role="special">()</phrase></code>
is used to interrupt the <code><phrase role="keyword">for</phrase></code>-loop
in <code><phrase role="identifier">f1</phrase><phrase role="special">()</phrase></code>.
</para>
<bridgehead renderas="sect3" id="context.ecv2.h6">
<phrase id="context.ecv2.class__code__phrase_role__identifier__execution_context__phrase___code_"/><link
linkend="context.ecv2.class__code__phrase_role__identifier__execution_context__phrase___code_">Class
@ -584,6 +645,7 @@
<phrase role="keyword">template</phrase><phrase role="special">&lt;</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Params</phrase> <phrase role="special">&gt;</phrase>
<phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">preallocated</phrase> <phrase role="identifier">palloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">segmented</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&amp;&amp;</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Params</phrase> <phrase role="special">&amp;&amp;</phrase> <phrase role="special">...</phrase> <phrase role="identifier">params</phrase><phrase role="special">)=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
<phrase role="special">~</phrase><phrase role="identifier">execution_context</phrase><phrase role="special">();</phrase>
<phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">execution_context</phrase> <phrase role="special">&amp;&amp;</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>

View File

@ -364,12 +364,58 @@ arguments.
f2: entered: 5
f1: entered third time: -1
The expression `ctx(ctx::exec_ontop_arg,f2,data+1)` executes `f2()` on top of
context `ctx`, e.g. an additional stack frame is allocated on top of the context
stack (in front of `f1()`). `f1()` returns argument `-1` that will returned by
the second invocation of `ctx(data+1)` in `f1()`.
Another option is to execute a function on top of the context, that throws an
exception.
struct interrupt {
boost::context::execution_context< void > ctx;
interrupt( boost::context::execution_context< void > && ctx_) :
ctx( std::forward< boost::context::execution_context< void > >( ctx_) ) {
}
};
boost::context::execution_context<void> f1(boost::context::execution_context<void> ctx) {
try {
for (;;) {
std::cout << "f1()" << std::endl;
ctx = ctx();
}
} catch (interrupt & e) {
std::cout << "f1(): interrupted" << std::endl;
ctx = std::move( e.ctx);
}
return ctx;
}
boost::context::execution_context<void> f2(boost::context::execution_context<void> ctx) {
throw interrupt(std::move(ctx));
return ctx;
}
boost::context::execution_context< void > ctx(f1);
ctx = ctx();
ctx = ctx();
ctx = ctx(boost::context::exec_ontop_arg,f2);
output:
f1()
f1()
f1(): interrupted
In this example `f2()` is used to interrupt the `for`-loop in `f1()`.
[heading Class `execution_context`]
struct exec_ontop_arg_t {};
const exec_ontop_arg_t exec_ontop_arg{};
template< typename ... Args >
class execution_context {
public:
@ -387,6 +433,7 @@ arguments.
template< typename Fn, typename ... Params >
execution_context( std::allocator_arg_t, preallocated palloc, segmented, Fn && fn, Params && ... params)= delete;
~execution_context();
execution_context( execution_context && other) noexcept;

View File

@ -469,6 +469,59 @@
<span class="identifier">f2</span><span class="special">:</span> <span class="identifier">entered</span><span class="special">:</span> <span class="number">5</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>
</pre>
<p>
The expression <code class="computeroutput"><span class="identifier">ctx</span><span class="special">(</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">exec_ontop_arg</span><span class="special">,</span><span class="identifier">f2</span><span class="special">,</span><span class="identifier">data</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code> executes <code class="computeroutput"><span class="identifier">f2</span><span class="special">()</span></code> on top of context <code class="computeroutput"><span class="identifier">ctx</span></code>,
e.g. an additional stack frame is allocated on top of the context stack (in
front of <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>).
<code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>
returns argument <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>
that will returned by the second invocation of <code class="computeroutput"><span class="identifier">ctx</span><span class="special">(</span><span class="identifier">data</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code> in <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>.
</p>
<p>
Another option is to execute a function on top of the context, that throws
an exception.
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">interrupt</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="identifier">execution_context</span><span class="special">&lt;</span> <span class="keyword">void</span> <span class="special">&gt;</span> <span class="identifier">ctx</span><span class="special">;</span>
<span class="identifier">interrupt</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="identifier">execution_context</span><span class="special">&lt;</span> <span class="keyword">void</span> <span class="special">&gt;</span> <span class="special">&amp;&amp;</span> <span class="identifier">ctx_</span><span class="special">)</span> <span class="special">:</span>
<span class="identifier">ctx</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">forward</span><span class="special">&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">execution_context</span><span class="special">&lt;</span> <span class="keyword">void</span> <span class="special">&gt;</span> <span class="special">&gt;(</span> <span class="identifier">ctx_</span><span class="special">)</span> <span class="special">)</span> <span class="special">{</span>
<span class="special">}</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="identifier">execution_context</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">f1</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="identifier">execution_context</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">ctx</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">try</span> <span class="special">{</span>
<span class="keyword">for</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()"</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">ctx</span> <span class="special">=</span> <span class="identifier">ctx</span><span class="special">();</span>
<span class="special">}</span>
<span class="special">}</span> <span class="keyword">catch</span> <span class="special">(</span><span class="identifier">interrupt</span> <span class="special">&amp;</span> <span class="identifier">e</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(): interrupted"</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">ctx</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">e</span><span class="special">.</span><span class="identifier">ctx</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="identifier">ctx</span><span class="special">;</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="identifier">execution_context</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">f2</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="identifier">execution_context</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">ctx</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">throw</span> <span class="identifier">interrupt</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">ctx</span><span class="special">));</span>
<span class="keyword">return</span> <span class="identifier">ctx</span><span class="special">;</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="identifier">execution_context</span><span class="special">&lt;</span> <span class="keyword">void</span> <span class="special">&gt;</span> <span class="identifier">ctx</span><span class="special">(</span><span class="identifier">f1</span><span class="special">);</span>
<span class="identifier">ctx</span> <span class="special">=</span> <span class="identifier">ctx</span><span class="special">();</span>
<span class="identifier">ctx</span> <span class="special">=</span> <span class="identifier">ctx</span><span class="special">();</span>
<span class="identifier">ctx</span> <span class="special">=</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="identifier">exec_ontop_arg</span><span class="special">,</span><span class="identifier">f2</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">f1</span><span class="special">()</span>
<span class="identifier">f1</span><span class="special">():</span> <span class="identifier">interrupted</span>
</pre>
<p>
In this example <code class="computeroutput"><span class="identifier">f2</span><span class="special">()</span></code>
is used to interrupt the <code class="computeroutput"><span class="keyword">for</span></code>-loop
in <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>.
</p>
<h4>
<a name="context.ecv2.h6"></a>
<span><a name="context.ecv2.class__code__phrase_role__identifier__execution_context__phrase___code_"></a></span><a class="link" href="ecv2.html#context.ecv2.class__code__phrase_role__identifier__execution_context__phrase___code_">Class
@ -494,6 +547,7 @@
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">typename</span> <span class="special">...</span> <span class="identifier">Params</span> <span class="special">&gt;</span>
<span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_arg_t</span><span class="special">,</span> <span class="identifier">preallocated</span> <span class="identifier">palloc</span><span class="special">,</span> <span class="identifier">segmented</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&amp;&amp;</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">Params</span> <span class="special">&amp;&amp;</span> <span class="special">...</span> <span class="identifier">params</span><span class="special">)=</span> <span class="keyword">delete</span><span class="special">;</span>
<span class="special">~</span><span class="identifier">execution_context</span><span class="special">();</span>
<span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">execution_context</span> <span class="special">&amp;&amp;</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>

View File

@ -67,7 +67,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: February 10, 2016 at 20:01:10 GMT</small></p></td>
<td align="left"><p><small>Last revised: February 10, 2016 at 20:47:15 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>