diff options
Diffstat (limited to 'libs/context/doc')
46 files changed, 6030 insertions, 75 deletions
diff --git a/libs/context/doc/acknowledgements.qbk b/libs/context/doc/acknowledgements.qbk index 257b83dcf..df69bd5a4 100644 --- a/libs/context/doc/acknowledgements.qbk +++ b/libs/context/doc/acknowledgements.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/architectures.qbk b/libs/context/doc/architectures.qbk index 1eedc2499..b1ddd62d1 100644 --- a/libs/context/doc/architectures.qbk +++ b/libs/context/doc/architectures.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/context.qbk b/libs/context/doc/context.qbk index b576ed270..9b801e644 100644 --- a/libs/context/doc/context.qbk +++ b/libs/context/doc/context.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt @@ -8,7 +8,7 @@ [library Context [quickbook 1.5] [authors [Kowalke, Oliver]] - [copyright 2009 Oliver Kowalke] + [copyright 2014 Oliver Kowalke] [id context] [purpose C++ Library for swiching different user ctx] [category text] @@ -22,8 +22,6 @@ [def __boost_build__ [*Boost.Build]] [def __boost_context__ [*Boost.Context]] -[def __boost_fiber__ [*Boost.Coroutine]] -[def __boost_task__ [*Boost.Task]] [template cs_example_link[link_text] [link context.examples.enumerator [link_text]]] [template context_link[link_text] [link context.context.context [link_text]]] @@ -42,9 +40,16 @@ [def __threads__ ['threads]] [def __tls__ ['thread-local storage]] [def __stack_allocator__ ['StackAllocator]] +[def __stack_allocator_concept__ ['stack-allocator concept]] +[def __stack_traits__ ['stack-traits]] +[def __econtext__ ['execution_context]] [def __fcontext__ ['fcontext_t]] [def __ucontext__ ['ucontext_t]] +[def __fixedsize__ ['fixedsize_stack]] +[def __protected_fixedsize__ ['protected_fixedsize_stack]] +[def __segmented__ ['segmented_stack]] +[def __stack_context__ ['stack_context]] [def __fls_alloc__ ['::FlsAlloc()]] [def __fls_free__ ['::FlsFree()]] @@ -65,6 +70,8 @@ [include overview.qbk] [include requirements.qbk] [include fcontext.qbk] +[include execution_context.qbk] +[include stack.qbk] [include performance.qbk] [include architectures.qbk] [include rationale.qbk] diff --git a/libs/context/doc/context.xml b/libs/context/doc/context.xml new file mode 100644 index 000000000..f77e2173c --- /dev/null +++ b/libs/context/doc/context.xml @@ -0,0 +1,2283 @@ +<?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: 2015/03/05 16:26:31 $" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <libraryinfo> + <authorgroup> + <author> + <firstname>Oliver</firstname> <surname>Kowalke</surname> + </author> + </authorgroup> + <copyright> + <year>2014</year> <holder>Oliver Kowalke</holder> + </copyright> + <legalnotice id="context.legal"> + <para> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>) + </para> + </legalnotice> + <librarypurpose> + C++ Library for swiching different user ctx + </librarypurpose> + <librarycategory name="category:text"></librarycategory> + </libraryinfo> + <title>Context</title> + <section id="context.overview"> + <title><link linkend="context.overview">Overview</link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> is a foundational library that + provides a sort of cooperative multitasking on a single thread. By providing + an abstraction of the current execution state in the current thread, including + the stack (with local variables) and stack pointer, all registers and CPU flags, + and the instruction pointer, a <emphasis>fcontext_t</emphasis> instance represents + a specific point in the application's execution path. This is useful for building + higher-level abstractions, like <emphasis>coroutines</emphasis>, <emphasis>cooperative + threads (userland threads)</emphasis> or an equivalent to <ulink url="http://msdn.microsoft.com/en-us/library/9k7k7cf0%28v=vs.80%29.aspx">C# + keyword <emphasis>yield</emphasis></ulink> in C++. + </para> + <para> + A <emphasis>fcontext_t</emphasis> provides the means to suspend the current + execution path and to transfer execution control, thereby permitting another + <emphasis>fcontext_t</emphasis> to run on the current thread. This state full + transfer mechanism enables a <emphasis>fcontext_t</emphasis> to suspend execution + from within nested functions and, later, to resume from where it was suspended. + While the execution path represented by a <emphasis>fcontext_t</emphasis> only + runs on a single thread, it can be migrated to another thread at any given + time. + </para> + <para> + A context switch between threads requires system calls (involving the OS kernel), + which can cost more than thousand CPU cycles on x86 CPUs. By contrast, transferring + control among them requires only few CPU cycles because it does not involve + system calls as it is done within a single thread. + </para> + <para> + In order to use the classes and functions described here, you can either include + the specific headers specified by the descriptions of each class or function, + or include the master library header: + </para> +<programlisting><phrase role="preprocessor">#include</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">all</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> +</programlisting> + <para> + which includes all the other headers in turn. + </para> + <para> + All functions and classes are contained in the namespace <emphasis>boost::context</emphasis>. + </para> + </section> + <section id="context.requirements"> + <title><link linkend="context.requirements">Requirements</link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> must be built for the particular + compiler(s) and CPU architecture(s)s being targeted. <emphasis role="bold">Boost.Context</emphasis> + includes assembly code and, therefore, requires GNU as and GNU preprocesspr + for supported POSIX systems, MASM for Windows/x86 systems and ARMasm for Windows/arm + systems. + </para> + <note> + <para> + MASM64 (ml64.exe) is a part of Microsoft's Windows Driver Kit. + </para> + </note> + <important> + <para> + Please note that <code><phrase role="identifier">address</phrase><phrase + role="special">-</phrase><phrase role="identifier">model</phrase><phrase + role="special">=</phrase><phrase role="number">64</phrase></code> must be + given to bjam command line on 64bit Windows for 64bit build; otherwise 32bit + code will be generated. + </para> + </important> + <important> + <para> + For cross-compiling the lib you must specify certain additional properties + at bjam command line: <code><phrase role="identifier">target</phrase><phrase + role="special">-</phrase><phrase role="identifier">os</phrase></code>, <code><phrase + role="identifier">abi</phrase></code>, <code><phrase role="identifier">binary</phrase><phrase + role="special">-</phrase><phrase role="identifier">format</phrase></code>, + <code><phrase role="identifier">architecture</phrase></code> and <code><phrase + role="identifier">address</phrase><phrase role="special">-</phrase><phrase + role="identifier">model</phrase></code>. + </para> + </important> + </section> + <section id="context.context"> + <title><link linkend="context.context">Struct fcontext_t</link></title> + <para> + Each instance of <emphasis>fcontext_t</emphasis> represents a context (CPU + registers and stack space). Together with its related functions <emphasis>jump_fcontext()</emphasis> + and <emphasis>make_fcontext()</emphasis> it provides a execution control transfer + mechanism similar interface like <ulink url="http://www.kernel.org/doc/man-pages/online/pages/man2/getcontext.2.html">ucontext_t</ulink>. + <emphasis>fcontext_t</emphasis> and its functions are located in <emphasis>boost::context</emphasis> + and the functions are declared as extern "C". + </para> + <warning> + <para> + If <emphasis>fcontext_t</emphasis> is used in a multi threaded application, + it can migrated between threads, but must not reference <emphasis>thread-local + storage</emphasis>. + </para> + </warning> + <important> + <para> + The low level API is the part to port to new platforms. + </para> + </important> + <note> + <para> + If <emphasis>fiber-local storage</emphasis> is used on Windows, the user + is responsible for calling <emphasis>::FlsAlloc()</emphasis>, <emphasis>::FlsFree()</emphasis>. + </para> + </note> + <bridgehead renderas="sect3" id="context.context.h0"> + <phrase id="context.context.executing_a_context"/><link linkend="context.context.executing_a_context">Executing + a context</link> + </bridgehead> + <para> + A new context supposed to execute a <emphasis>context-function</emphasis> (returning + void and accepting intptr_t as argument) will be created on top of the stack + (at 16 byte boundary) by function <emphasis>make_fcontext()</emphasis>. + </para> +<programlisting><phrase role="comment">// context-function</phrase> +<phrase role="keyword">void</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase><phrase role="identifier">intptr</phrase><phrase role="special">);</phrase> + +<phrase role="comment">// creates a new stack</phrase> +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="number">8192</phrase><phrase role="special">;</phrase> +<phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">malloc</phrase><phrase role="special">(</phrase><phrase role="identifier">size</phrase><phrase role="special">));</phrase> + +<phrase role="comment">// context fc uses f() as context function</phrase> +<phrase role="comment">// fcontext_t is placed on top of context stack</phrase> +<phrase role="comment">// a pointer to fcontext_t is returned</phrase> +<phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">fc</phrase><phrase role="special">(</phrase><phrase role="identifier">make_fcontext</phrase><phrase role="special">(</phrase><phrase role="identifier">sp</phrase><phrase role="special">,</phrase><phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase role="identifier">f</phrase><phrase role="special">));</phrase> +</programlisting> + <para> + Calling <emphasis>jump_fcontext()</emphasis> invokes the <emphasis>context-function</emphasis> + in a newly created context complete with registers, flags, stack and instruction + pointers. When control should be returned to the original calling context, + call <emphasis>jump_fcontext()</emphasis>. The current context information + (registers, flags, and stack and instruction pointers) is saved and the original + context information is restored. Calling <emphasis>jump_fcontext()</emphasis> + again resumes execution in the second context after saving the new state of + the original context. + </para> +<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="identifier">fc1</phrase><phrase role="special">,</phrase><phrase role="identifier">fc2</phrase><phrase role="special">;</phrase> + +<phrase role="keyword">void</phrase> <phrase role="identifier">f1</phrase><phrase role="special">(</phrase><phrase role="identifier">intptr_t</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"><<</phrase><phrase role="string">"f1: entered"</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="string">"f1: call jump_fcontext( & fc1, fc2, 0)"</phrase><phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fc1</phrase><phrase role="special">,</phrase><phrase role="identifier">fc2</phrase><phrase role="special">,</phrase><phrase role="number">0</phrase><phrase role="special">);</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="string">"f1: return"</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fc1</phrase><phrase role="special">,</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="number">0</phrase><phrase role="special">);</phrase> +<phrase role="special">}</phrase> + +<phrase role="keyword">void</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase><phrase role="identifier">intptr_t</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"><<</phrase><phrase role="string">"f2: entered"</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="string">"f2: call jump_fcontext( & fc2, fc1, 0)"</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fc2</phrase><phrase role="special">,</phrase><phrase role="identifier">fc1</phrase><phrase role="special">,</phrase><phrase role="number">0</phrase><phrase role="special">);</phrase> + <phrase role="identifier">BOOST_ASSERT</phrase><phrase role="special">(</phrase><phrase role="keyword">false</phrase><phrase role="special">&&!</phrase><phrase role="string">"f2: never returns"</phrase><phrase role="special">);</phrase> +<phrase role="special">}</phrase> + +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">(</phrase><phrase role="number">8192</phrase><phrase role="special">);</phrase> +<phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp1</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">malloc</phrase><phrase role="special">(</phrase><phrase role="identifier">size</phrase><phrase role="special">));</phrase> +<phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp2</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">malloc</phrase><phrase role="special">(</phrase><phrase role="identifier">size</phrase><phrase role="special">));</phrase> + +<phrase role="identifier">fc1</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">make_fcontext</phrase><phrase role="special">(</phrase><phrase role="identifier">sp1</phrase><phrase role="special">,</phrase><phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase role="identifier">f1</phrase><phrase role="special">);</phrase> +<phrase role="identifier">fc2</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">make_fcontext</phrase><phrase role="special">(</phrase><phrase role="identifier">sp2</phrase><phrase role="special">,</phrase><phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase role="identifier">f2</phrase><phrase role="special">);</phrase> + +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="string">"main: call jump_fcontext( & fcm, fc1, 0)"</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="identifier">fc1</phrase><phrase role="special">,</phrase><phrase role="number">0</phrase><phrase role="special">);</phrase> + +<phrase role="identifier">output</phrase><phrase role="special">:</phrase> + <phrase role="identifier">main</phrase><phrase role="special">:</phrase> <phrase role="identifier">call</phrase> <phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> + <phrase role="identifier">f1</phrase><phrase role="special">:</phrase> <phrase role="identifier">entered</phrase> + <phrase role="identifier">f1</phrase><phrase role="special">:</phrase> <phrase role="identifier">call</phrase> <phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</phrase> <phrase role="identifier">fc2</phrase><phrase role="special">,</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> + <phrase role="identifier">f2</phrase><phrase role="special">:</phrase> <phrase role="identifier">entered</phrase> + <phrase role="identifier">f2</phrase><phrase role="special">:</phrase> <phrase role="identifier">call</phrase> <phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">fc2</phrase><phrase role="special">,</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> + <phrase role="identifier">f1</phrase><phrase role="special">:</phrase> <phrase role="keyword">return</phrase> +</programlisting> + <para> + First call of <emphasis>jump_fcontext()</emphasis> enters the <emphasis>context-function</emphasis> + <code><phrase role="identifier">f1</phrase><phrase role="special">()</phrase></code> + by starting context fc1 (context fcm saves the registers of <code><phrase role="identifier">main</phrase><phrase + role="special">()</phrase></code>). For jumping between context's fc1 and fc2 + <code><phrase role="identifier">jump_fcontext</phrase><phrase role="special">()</phrase></code> + is called. Because context fcm is chained to fc1, <code><phrase role="identifier">main</phrase><phrase + role="special">()</phrase></code> is entered (returning from <emphasis>jump_fcontext()</emphasis>) + after context fc1 becomes complete (return from <code><phrase role="identifier">f1</phrase><phrase + role="special">()</phrase></code>). + </para> + <warning> + <para> + Calling <emphasis>jump_fcontext()</emphasis> to the same context from inside + the same context results in undefined behaviour. + </para> + </warning> + <important> + <para> + The size of the stack is required to be larger than the size of fcontext_t. + </para> + </important> + <note> + <para> + In contrast to threads, which are preemtive, <emphasis>fcontext_t</emphasis> + switches are cooperative (programmer controls when switch will happen). The + kernel is not involved in the context switches. + </para> + </note> + <bridgehead renderas="sect3" id="context.context.h1"> + <phrase id="context.context.transfer_of_data"/><link linkend="context.context.transfer_of_data">Transfer + of data</link> + </bridgehead> + <para> + The third argument passed to <emphasis>jump_fcontext()</emphasis>, in one context, + is passed as the first argument of the <emphasis>context-function</emphasis> + if the context is started for the first time. In all following invocations + of <emphasis>jump_fcontext()</emphasis> the intptr_t passed to <emphasis>jump_fcontext()</emphasis>, + in one context, is returned by <emphasis>jump_fcontext()</emphasis> in the + other context. + </para> +<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="identifier">fc</phrase><phrase role="special">;</phrase> + +<phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">pair</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">,</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">pair_t</phrase><phrase role="special">;</phrase> + +<phrase role="keyword">void</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase><phrase role="identifier">intptr_t</phrase> <phrase role="identifier">param</phrase><phrase role="special">)</phrase> +<phrase role="special">{</phrase> + <phrase role="identifier">pair_t</phrase><phrase role="special">*</phrase> <phrase role="identifier">p</phrase><phrase role="special">=(</phrase><phrase role="identifier">pair_t</phrase><phrase role="special">*)</phrase><phrase role="identifier">param</phrase><phrase role="special">;</phrase> + <phrase role="identifier">p</phrase><phrase role="special">=(</phrase><phrase role="identifier">pair_t</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fc</phrase><phrase role="special">,</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,(</phrase><phrase role="identifier">intptr_t</phrase><phrase role="special">)(</phrase><phrase role="identifier">p</phrase><phrase role="special">-></phrase><phrase role="identifier">first</phrase><phrase role="special">+</phrase><phrase role="identifier">p</phrase><phrase role="special">-></phrase><phrase role="identifier">second</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fc</phrase><phrase role="special">,</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,(</phrase><phrase role="identifier">intptr_t</phrase><phrase role="special">)(</phrase><phrase role="identifier">p</phrase><phrase role="special">-></phrase><phrase role="identifier">first</phrase><phrase role="special">+</phrase><phrase role="identifier">p</phrase><phrase role="special">-></phrase><phrase role="identifier">second</phrase><phrase role="special">));</phrase> +<phrase role="special">}</phrase> + +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">(</phrase><phrase role="number">8192</phrase><phrase role="special">);</phrase> +<phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">malloc</phrase><phrase role="special">(</phrase><phrase role="identifier">size</phrase><phrase role="special">));</phrase> + +<phrase role="identifier">pair_t</phrase> <phrase role="identifier">p</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_pair</phrase><phrase role="special">(</phrase><phrase role="number">2</phrase><phrase role="special">,</phrase><phrase role="number">7</phrase><phrase role="special">));</phrase> +<phrase role="identifier">fc</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">make_fcontext</phrase><phrase role="special">(</phrase><phrase role="identifier">sp</phrase><phrase role="special">,</phrase><phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase role="identifier">f</phrase><phrase role="special">);</phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">res</phrase><phrase role="special">=(</phrase><phrase role="keyword">int</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="identifier">fc</phrase><phrase role="special">,(</phrase><phrase role="identifier">intptr_t</phrase><phrase role="special">)&</phrase><phrase role="identifier">p</phrase><phrase role="special">);</phrase> +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">first</phrase><phrase role="special"><<</phrase><phrase role="string">" + "</phrase><phrase role="special"><<</phrase><phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">second</phrase><phrase role="special"><<</phrase><phrase role="string">" == "</phrase><phrase role="special"><<</phrase><phrase role="identifier">res</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + +<phrase role="identifier">p</phrase><phrase role="special">=</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_pair</phrase><phrase role="special">(</phrase><phrase role="number">5</phrase><phrase role="special">,</phrase><phrase role="number">6</phrase><phrase role="special">);</phrase> +<phrase role="identifier">res</phrase><phrase role="special">=(</phrase><phrase role="keyword">int</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">jump_fcontext</phrase><phrase role="special">(&</phrase><phrase role="identifier">fcm</phrase><phrase role="special">,</phrase><phrase role="identifier">fc</phrase><phrase role="special">,(</phrase><phrase role="identifier">intptr_t</phrase><phrase role="special">)&</phrase><phrase role="identifier">p</phrase><phrase role="special">);</phrase> +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase><phrase role="special"><<</phrase><phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">first</phrase><phrase role="special"><<</phrase><phrase role="string">" + "</phrase><phrase role="special"><<</phrase><phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">second</phrase><phrase role="special"><<</phrase><phrase role="string">" == "</phrase><phrase role="special"><<</phrase><phrase role="identifier">res</phrase><phrase role="special"><<</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + +<phrase role="identifier">output</phrase><phrase role="special">:</phrase> + <phrase role="number">2</phrase> <phrase role="special">+</phrase> <phrase role="number">7</phrase> <phrase role="special">==</phrase> <phrase role="number">9</phrase> + <phrase role="number">5</phrase> <phrase role="special">+</phrase> <phrase role="number">6</phrase> <phrase role="special">==</phrase> <phrase role="number">11</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.context.h2"> + <phrase id="context.context.exceptions_in__emphasis_context_function__emphasis_"/><link + linkend="context.context.exceptions_in__emphasis_context_function__emphasis_">Exceptions + in <emphasis>context-function</emphasis></link> + </bridgehead> + <para> + If the <emphasis>context-function</emphasis> emits an exception, the behaviour + is undefined. + </para> + <important> + <para> + <emphasis>context-function</emphasis> should wrap the code in a try/catch + block. + </para> + </important> + <important> + <para> + Do not jump from inside a catch block and than re-throw the exception in + another execution context. + </para> + </important> + <bridgehead renderas="sect3" id="context.context.h3"> + <phrase id="context.context.preserving_floating_point_registers"/><link linkend="context.context.preserving_floating_point_registers">Preserving + floating point registers</link> + </bridgehead> + <para> + Preserving the floating point registers increases the cycle count for a context + switch (see performance tests). The fourth argument of <emphasis>jump_fcontext()</emphasis> + controls if fpu registers should be preserved by the context jump. + </para> + <important> + <para> + The use of the fpu controlling argument of <emphasis>jump_fcontext()</emphasis> + must be consistent in the application. Otherwise the behaviour is undefined. + </para> + </important> + <bridgehead renderas="sect3" id="context.context.h4"> + <phrase id="context.context.stack_unwinding"/><link linkend="context.context.stack_unwinding">Stack + unwinding</link> + </bridgehead> + <para> + Sometimes it is necessary to unwind the stack of an unfinished context to destroy + local stack variables so they can release allocated resources (RAII pattern). + The user is responsible for this task. + </para> + <bridgehead renderas="sect3" id="context.context.h5"> + <phrase id="context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"/><link + linkend="context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"><code><phrase + role="identifier">fcontext_t</phrase></code> and related functions</link> + </bridgehead> +<programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">stack_t</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">;</phrase> +<phrase role="special">};</phrase> + +<phrase role="keyword">typedef</phrase> <phrase role="special"><</phrase><phrase role="identifier">opaque</phrase> <phrase role="identifier">pointer</phrase> <phrase role="special">></phrase> <phrase role="identifier">fcontext_t</phrase><phrase role="special">;</phrase> + +<phrase role="identifier">intptr_t</phrase> <phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase><phrase role="identifier">fcontext_t</phrase><phrase role="special">*</phrase> <phrase role="identifier">ofc</phrase><phrase role="special">,</phrase><phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">nfc</phrase><phrase role="special">,</phrase><phrase role="identifier">intptr_t</phrase> <phrase role="identifier">vp</phrase><phrase role="special">,</phrase><phrase role="keyword">bool</phrase> <phrase role="identifier">preserve_fpu</phrase><phrase role="special">=</phrase><phrase role="keyword">true</phrase><phrase role="special">);</phrase> +<phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">make_fcontext</phrase><phrase role="special">(</phrase><phrase role="keyword">void</phrase><phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">,</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase role="special">)(</phrase><phrase role="identifier">intptr_t</phrase><phrase role="special">));</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.context.h6"> + <phrase id="context.context._code__phrase_role__identifier__sp__phrase___code_"/><link + linkend="context.context._code__phrase_role__identifier__sp__phrase___code_"><code><phrase + role="identifier">sp</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Member:</term> + <listitem> + <para> + Pointer to the beginning of the stack (depending of the architecture + the stack grows downwards or upwards). + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.context.h7"> + <phrase id="context.context._code__phrase_role__identifier__size__phrase___code_"/><link + linkend="context.context._code__phrase_role__identifier__size__phrase___code_"><code><phrase + role="identifier">size</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Member:</term> + <listitem> + <para> + Size of the stack in bytes. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.context.h8"> + <phrase id="context.context._code__phrase_role__identifier__fc_stack__phrase___code_"/><link + linkend="context.context._code__phrase_role__identifier__fc_stack__phrase___code_"><code><phrase + role="identifier">fc_stack</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Member:</term> + <listitem> + <para> + Tracks the memory for the context's stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.context.h9"> + <phrase id="context.context._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.context._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="identifier">intptr_t</phrase> <phrase role="identifier">jump_fcontext</phrase><phrase + role="special">(</phrase><phrase role="identifier">fcontext_t</phrase><phrase + role="special">*</phrase> <phrase role="identifier">ofc</phrase><phrase role="special">,</phrase><phrase + role="identifier">fcontext_t</phrase> <phrase role="identifier">nfc</phrase><phrase + role="special">,</phrase><phrase role="identifier">intptr_t</phrase> <phrase + role="identifier">p</phrase><phrase role="special">,</phrase><phrase role="keyword">bool</phrase> + <phrase role="identifier">preserve_fpu</phrase><phrase role="special">=</phrase><phrase + role="keyword">true</phrase><phrase role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Stores the current context data (stack pointer, instruction pointer, + and CPU registers) to <code><phrase role="special">*</phrase><phrase + role="identifier">ofc</phrase></code> and restores the context data from + <code><phrase role="identifier">nfc</phrase></code>, which implies jumping + to <code><phrase role="identifier">nfc</phrase></code>'s execution context. + The intptr_t argument, <code><phrase role="identifier">p</phrase></code>, + is passed to the current context to be returned by the most recent call + to <code><phrase role="identifier">jump_fcontext</phrase><phrase role="special">()</phrase></code> + in the same thread. The last argument controls if fpu registers have + to be preserved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + The third pointer argument passed to the most recent call to <code><phrase + role="identifier">jump_fcontext</phrase><phrase role="special">()</phrase></code>, + if any. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.context.h10"> + <phrase id="context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"><code><phrase + role="identifier">fcontext_t</phrase> <phrase role="identifier">make_fcontext</phrase><phrase + role="special">(</phrase><phrase role="keyword">void</phrase><phrase role="special">*</phrase> + <phrase role="identifier">sp</phrase><phrase role="special">,</phrase><phrase + role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> + <phrase role="identifier">size</phrase><phrase role="special">,</phrase><phrase + role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase + role="special">)(</phrase><phrase role="identifier">intptr_t</phrase><phrase + role="special">))</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Precondition:</term> + <listitem> + <para> + Stack <code><phrase role="identifier">sp</phrase></code> and function + pointer <code><phrase role="identifier">fn</phrase></code> are valid + (depending on the architecture <code><phrase role="identifier">sp</phrase></code> + points to the top or bottom of the stack) and <code><phrase role="identifier">size</phrase></code> + > 0. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Creates an fcontext_t on top of the stack and prepares the stack to execute + the <emphasis>context-function</emphasis> <code><phrase role="identifier">fn</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns a fcontext_t which is placed on the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.econtext"> + <title><link linkend="context.econtext">Class execution_context</link></title> + <important> + <para> + <emphasis>execution_context</emphasis> is supported only by C++14. + </para> + </important> + <para> + Class <emphasis>execution_context</emphasis> encapsulates <emphasis>fcontext_t</emphasis> + and related functions ( <emphasis>jump_fcontext()</emphasis> and <emphasis>make_fcontext()</emphasis>) + as well as stack management. <emphasis>execution_context</emphasis> permits + access to the current, active context via <code><phrase role="identifier">execution_context</phrase><phrase + role="special">::</phrase><phrase role="identifier">current</phrase><phrase + role="special">()</phrase></code>. + </para> +<programlisting><phrase role="comment">/* + * grammar: + * P ---> E '\0' + * E ---> T {('+'|'-') T} + * T ---> S {('*'|'/') S} + * S ---> digit | '(' E ')' + */</phrase> +<phrase role="keyword">class</phrase> <phrase role="identifier">Parser</phrase><phrase role="special">{</phrase> + <phrase role="comment">// implementation omitted; see examples directory</phrase> +<phrase role="special">};</phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">istringstream</phrase> <phrase role="identifier">is</phrase><phrase role="special">(</phrase><phrase role="string">"1+1"</phrase><phrase role="special">);</phrase> + <phrase role="keyword">bool</phrase> <phrase role="identifier">done</phrase><phrase role="special">=</phrase><phrase role="keyword">false</phrase><phrase role="special">;</phrase> + <phrase role="keyword">char</phrase> <phrase role="identifier">c</phrase><phrase role="special">;</phrase> + + <phrase role="comment">// create handle to main execution context</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="identifier">main_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">execution_context</phrase><phrase role="special">::</phrase><phrase role="identifier">current</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> + + <phrase role="comment">// executes parser in new execution context</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="identifier">parser_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">fixedsize_stack</phrase><phrase role="special">(),</phrase> + <phrase role="special">[&</phrase><phrase role="identifier">main_ctx</phrase><phrase role="special">,&</phrase><phrase role="identifier">is</phrase><phrase role="special">,&</phrase><phrase role="identifier">c</phrase><phrase role="special">,&</phrase><phrase role="identifier">done</phrase><phrase role="special">](){</phrase> + <phrase role="comment">// create parser with callback function</phrase> + <phrase role="identifier">Parser</phrase> <phrase role="identifier">p</phrase><phrase role="special">(</phrase><phrase role="identifier">is</phrase><phrase role="special">,</phrase> + <phrase role="special">[&</phrase><phrase role="identifier">main_ctx</phrase><phrase role="special">,&</phrase><phrase role="identifier">c</phrase><phrase role="special">](</phrase><phrase role="keyword">char</phrase> <phrase role="identifier">ch</phrase><phrase role="special">){</phrase> + <phrase role="identifier">c</phrase><phrase role="special">=</phrase><phrase role="identifier">ch</phrase><phrase role="special">;</phrase> + <phrase role="comment">// resume main execution context</phrase> + <phrase role="identifier">main_ctx</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="special">});</phrase> + <phrase role="comment">// start recursive parsing</phrase> + <phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">run</phrase><phrase role="special">();</phrase> + <phrase role="identifier">done</phrase><phrase role="special">=</phrase><phrase role="keyword">true</phrase><phrase role="special">;</phrase> + <phrase role="comment">// return to main execution context</phrase> + <phrase role="identifier">main_ctx</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="special">});</phrase> + + <phrase role="comment">// user-code pulls parsed data from parser</phrase> + <phrase role="comment">// inverted control flow</phrase> + <phrase role="identifier">parser_ctx</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="keyword">do</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">printf</phrase><phrase role="special">(</phrase><phrase role="string">"Parsed: %c\n"</phrase><phrase role="special">,</phrase><phrase role="identifier">c</phrase><phrase role="special">);</phrase> + <phrase role="identifier">parser_ctx</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="special">}</phrase> <phrase role="keyword">while</phrase><phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">done</phrase><phrase role="special">);</phrase> +<phrase role="special">}</phrase> + +<phrase role="identifier">output</phrase><phrase role="special">:</phrase> + <phrase role="identifier">Parsed</phrase><phrase role="special">:</phrase> <phrase role="number">1</phrase> + <phrase role="identifier">Parsed</phrase><phrase role="special">:</phrase> <phrase role="special">+</phrase> + <phrase role="identifier">Parsed</phrase><phrase role="special">:</phrase> <phrase role="number">1</phrase> +</programlisting> + <para> + In this example a recursive descent parser uses a callback to emit a newly + passed symbol. Using <emphasis>execution_context</emphasis> 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). + </para> + <para> + The interface of <emphasis>execution_context</emphasis> does not transfer data. + This is not required because usually sharing data's address (pointer/reference) + sufficient. + </para> + <para> + If the code executed by <emphasis>execution_context</emphasis> emits an exception, + <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase + role="identifier">terminate</phrase><phrase role="special">()</phrase></code> + will be called. + </para> + <important> + <para> + Do not jump from inside a catch block and than re-throw exceptions in another + execution context. + </para> + </important> + <para> + Sometimes it is necessary to unwind the stack of an unfinished context to destroy + local stack variables so they can release allocated resources (RAII pattern). + The user is responsible for this task. + </para> + <bridgehead renderas="sect3" id="context.econtext.h0"> + <phrase id="context.econtext.allocating_control_strutures_on_top_of_stack"/><link + linkend="context.econtext.allocating_control_strutures_on_top_of_stack">allocating + control strutures on top of stack</link> + </bridgehead> + <para> + Allocating control structures on top of the stack requires to allocated the + <emphasis>stack_context</emphasis> and create the control structure with placement + new before <emphasis>execution_context</emphasis> is created. + </para> + <note> + <para> + The user is responsible for destructing the control structure at the top + of the stack. + </para> + </note> +<programlisting><phrase role="comment">// stack-alloctor used for (de-)allocating stack</phrase> +<phrase role="identifier">fixedsize_stack</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">(</phrase> <phrase role="number">4048</phrase><phrase role="special">);</phrase> +<phrase role="comment">// allocate stack space</phrase> +<phrase role="identifier">stack_context</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">(</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> +<phrase role="comment">// reserve space for control structure on top of the stack</phrase> +<phrase role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase> <phrase role="special">=</phrase> <phrase role="keyword">static_cast</phrase><phrase role="special"><</phrase> <phrase role="keyword">char</phrase> <phrase role="special">*</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase role="identifier">sp</phrase><phrase role="special">)</phrase> <phrase role="special">-</phrase> <phrase role="keyword">sizeof</phrase><phrase role="special">(</phrase> <phrase role="identifier">my_control_structure</phrase><phrase role="special">);</phrase> +<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase role="identifier">size</phrase> <phrase role="special">-</phrase> <phrase role="keyword">sizeof</phrase><phrase role="special">(</phrase> <phrase role="identifier">my_control_structure</phrase><phrase role="special">);</phrase> +<phrase role="comment">// placement new creates control structure on reserved space</phrase> +<phrase role="identifier">my_control_structure</phrase> <phrase role="special">*</phrase> <phrase role="identifier">cs</phrase> <phrase role="special">=</phrase> <phrase role="keyword">new</phrase> <phrase role="special">(</phrase> <phrase role="identifier">sp</phrase><phrase role="special">)</phrase> <phrase role="identifier">my_control_structure</phrase><phrase role="special">(</phrase> <phrase role="identifier">sp</phrase><phrase role="special">,</phrase> <phrase role="identifier">size</phrase><phrase role="special">,</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">,</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">);</phrase> +<phrase role="special">...</phrase> +<phrase role="comment">// destructing the control structure</phrase> +<phrase role="identifier">cs</phrase><phrase role="special">->~</phrase><phrase role="identifier">my_control_structure</phrase><phrase role="special">();</phrase> +<phrase role="special">...</phrase> +<phrase role="keyword">struct</phrase> <phrase role="identifier">my_control_structure</phrase> <phrase role="special">{</phrase> + <phrase role="comment">// execution context</phrase> + <phrase role="identifier">execution_context</phrase> <phrase role="identifier">ectx</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="special">></phrase> + <phrase role="identifier">my_control_structure</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">,</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> + <phrase role="comment">// create execution context</phrase> + <phrase role="identifier">ectx</phrase><phrase role="special">(</phrase> <phrase role="identifier">preallocated</phrase><phrase role="special">(</phrase> <phrase role="identifier">sp</phrase><phrase role="special">,</phrase> <phrase role="identifier">size</phrase><phrase role="special">,</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">),</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">entry_func</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> + <phrase role="special">}</phrase> + <phrase role="special">...</phrase> +<phrase role="special">};</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.econtext.h1"> + <phrase id="context.econtext.exception_handling"/><link linkend="context.econtext.exception_handling">exception + handling</link> + </bridgehead> + <para> + If the function executed inside a <emphasis>execution_context</emphasis> emitts + ans exception, <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase + role="identifier">terminate</phrase><phrase role="special">()</phrase></code> + is called - <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase + role="identifier">exception_ptr</phrase></code> can used to store exceptions + thrown inside the other context. + </para> +<programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">X</phrase> <phrase role="special">{</phrase> +<phrase role="keyword">private</phrase><phrase role="special">:</phrase> + <phrase role="keyword">int</phrase> <phrase role="special">*</phrase> <phrase role="identifier">inp_</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">outp_</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">excptr_</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="identifier">caller_</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="identifier">callee_</phrase><phrase role="special">;</phrase> + +<phrase role="keyword">public</phrase><phrase role="special">:</phrase> + <phrase role="identifier">X</phrase><phrase role="special">()</phrase> <phrase role="special">:</phrase> + <phrase role="identifier">inp_</phrase><phrase role="special">(</phrase> <phrase role="keyword">nullptr</phrase><phrase role="special">),</phrase> + <phrase role="identifier">outp_</phrase><phrase role="special">(),</phrase> + <phrase role="identifier">excptr_</phrase><phrase role="special">(),</phrase> + <phrase role="identifier">caller_</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">::</phrase><phrase role="identifier">current</phrase><phrase role="special">()</phrase> <phrase role="special">),</phrase> + <phrase role="identifier">callee_</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">fixedsize_stack</phrase><phrase role="special">(),</phrase> + <phrase role="special">[=]</phrase> <phrase role="special">()</phrase> <phrase role="special">{</phrase> + <phrase role="keyword">try</phrase> <phrase role="special">{</phrase> + <phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="special">*</phrase> <phrase role="identifier">inp_</phrase><phrase role="special">;</phrase> + <phrase role="identifier">outp_</phrase> <phrase role="special">=</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">lexical_cast</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">i</phrase><phrase role="special">);</phrase> + <phrase role="identifier">caller_</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="special">}</phrase> <phrase role="keyword">catch</phrase> <phrase role="special">(...)</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">excptr_</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">current_exception</phrase><phrase role="special">();</phrase> + <phrase role="special">}</phrase> + <phrase role="special">})</phrase> + <phrase role="special">{}</phrase> + + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">inp_</phrase> <phrase role="special">=</phrase> <phrase role="special">&</phrase> <phrase role="identifier">i</phrase><phrase role="special">;</phrase> + <phrase role="identifier">callee_</phrase><phrase role="special">.</phrase><phrase role="identifier">resume</phrase><phrase role="special">();</phrase> + <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">excptr_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">rethrow_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">excptr_</phrase><phrase role="special">);</phrase> + <phrase role="special">}</phrase> + <phrase role="keyword">return</phrase> <phrase role="identifier">outp_</phrase><phrase role="special">;</phrase> + <phrase role="special">}</phrase> +<phrase role="special">};</phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> + <phrase role="identifier">X</phrase> <phrase role="identifier">x</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">x</phrase><phrase role="special">(</phrase> <phrase role="number">7</phrase><phrase role="special">)</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"done"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.econtext.h2"> + <phrase id="context.econtext.class__code__phrase_role__identifier__execution_context__phrase___code_"/><link + linkend="context.econtext.class__code__phrase_role__identifier__execution_context__phrase___code_">Class + <code><phrase role="identifier">execution_context</phrase></code></link> + </bridgehead> +<programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">execution_context</phrase> <phrase role="special">{</phrase> +<phrase role="keyword">public</phrase><phrase role="special">:</phrase> + <phrase role="keyword">static</phrase> <phrase role="identifier">execution_context</phrase> <phrase role="identifier">current</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> + <phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase> + + <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase role="special">,</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">Args</phrase> <phrase role="special">></phrase> + <phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> + + <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> + <phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">preallocated</phrase> <phrase role="identifier">palloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase> + + <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase role="special">,</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">Args</phrase> <phrase role="special">></phrase> + <phrase role="identifier">execution_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">preallocated</phrase> <phrase role="identifier">palloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> + + <phrase role="keyword">void</phrase> <phrase role="identifier">resume</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">explicit</phrase> <phrase role="keyword">operator</phrase> <phrase role="keyword">bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> +<phrase role="special">};</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.econtext.h3"> + <phrase id="context.econtext._code__phrase_role__keyword__static__phrase___phrase_role__identifier__execution_context__phrase___phrase_role__identifier__current__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__static__phrase___phrase_role__identifier__execution_context__phrase___phrase_role__identifier__current__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="identifier">execution_context</phrase> + <phrase role="identifier">current</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns an instance of excution_context pointing to the active execution + context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h4"> + <phrase id="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"><code><phrase + role="keyword">template</phrase><phrase role="special"><</phrase> <phrase + role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">typname</phrase> <phrase + role="identifier">Fn</phrase> <phrase role="special">></phrase> <phrase + role="identifier">execution_context</phrase><phrase role="special">(</phrase> + <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> + <phrase role="identifier">fn</phrase><phrase role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Creates a new execution context and prepares the context to execute + <code><phrase role="identifier">fn</phrase></code>. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h5"> + <phrase id="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="keyword">template</phrase><phrase role="special"><</phrase> <phrase + role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">typname</phrase> <phrase + role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> + <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> + <phrase role="special">></phrase> <phrase role="identifier">execution_context</phrase><phrase + role="special">(</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase + role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase + role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase + role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> + <phrase role="special">&&</phrase> <phrase role="special">...</phrase> + <phrase role="identifier">args</phrase><phrase role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Creates a new execution context and prepares the context to execute + <code><phrase role="identifier">fn</phrase></code>. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h6"> + <phrase id="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"><code><phrase + role="keyword">template</phrase><phrase role="special"><</phrase> <phrase + role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">typname</phrase> <phrase + role="identifier">Fn</phrase> <phrase role="special">></phrase> <phrase + role="identifier">execution_context</phrase><phrase role="special">(</phrase> + <phrase role="identifier">preallocated</phrase> <phrase role="identifier">palloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">StackAlloc</phrase> <phrase + role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase + role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase + role="identifier">fn</phrase><phrase role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Creates a new execution context and prepares the context to execute + <code><phrase role="identifier">fn</phrase></code>. Used to store control + structures on top of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h7"> + <phrase id="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="keyword">template</phrase><phrase role="special"><</phrase> <phrase + role="keyword">typename</phrase> <phrase role="identifier">StackAlloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">typname</phrase> <phrase + role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> + <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> + <phrase role="special">></phrase> <phrase role="identifier">execution_context</phrase><phrase + role="special">(</phrase> <phrase role="identifier">preallocated</phrase> + <phrase role="identifier">palloc</phrase><phrase role="special">,</phrase> + <phrase role="identifier">StackAlloc</phrase> <phrase role="identifier">salloc</phrase><phrase + role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> + <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase + role="identifier">Args</phrase> <phrase role="special">&&</phrase> + <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase + role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Creates a new execution context and prepares the context to execute + <code><phrase role="identifier">fn</phrase></code>. Used to store control + structures on top of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h8"> + <phrase id="context.econtext._code__phrase_role__keyword__void__phrase___phrase_role__identifier__resume__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__void__phrase___phrase_role__identifier__resume__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">void</phrase> <phrase role="identifier">resume</phrase><phrase + role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Stores internally the current context data (stack pointer, instruction + pointer, and CPU registers) to the current active context and restores + the context data from <code><phrase role="special">*</phrase><phrase + role="keyword">this</phrase></code>, which implies jumping to <code><phrase + role="special">*</phrase><phrase role="keyword">this</phrase></code>'s + execution context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Note:</term> + <listitem> + <para> + The behaviour is undefined if <code><phrase role="identifier">resume</phrase><phrase + role="special">()</phrase></code> is called while <code><phrase role="identifier">execution_context</phrase><phrase + role="special">::</phrase><phrase role="identifier">current</phrase><phrase + role="special">()</phrase></code> returns <code><phrase role="special">*</phrase><phrase + role="keyword">this</phrase></code> (e.g. resuming an alredy running + cotnext). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h9"> + <phrase id="context.econtext._code__phrase_role__keyword__explicit__phrase___phrase_role__keyword__operator__phrase___phrase_role__keyword__bool__phrase__phrase_role__special______phrase___phrase_role__keyword__const__phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__explicit__phrase___phrase_role__keyword__operator__phrase___phrase_role__keyword__bool__phrase__phrase_role__special______phrase___phrase_role__keyword__const__phrase___code_"><code><phrase + role="keyword">explicit</phrase> <phrase role="keyword">operator</phrase> + <phrase role="keyword">bool</phrase><phrase role="special">()</phrase> <phrase + role="keyword">const</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> + refers to an invalid context or the context-function has returned (completed), + the function returns <code><phrase role="keyword">false</phrase></code>. + Otherwise <code><phrase role="keyword">true</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h10"> + <phrase id="context.econtext._code__phrase_role__keyword__bool__phrase___phrase_role__keyword__operator__phrase__phrase_role__special_______phrase___phrase_role__keyword__const__phrase___code_"/><link + linkend="context.econtext._code__phrase_role__keyword__bool__phrase___phrase_role__keyword__operator__phrase__phrase_role__special_______phrase___phrase_role__keyword__const__phrase___code_"><code><phrase + role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase + role="special">!()</phrase> <phrase role="keyword">const</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> + refers to an invalid context or the context-function has returned (completed), + the function returns <code><phrase role="keyword">true</phrase></code>. + Otherwise <code><phrase role="keyword">false</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect3" id="context.econtext.h11"> + <phrase id="context.econtext.struct__code__phrase_role__identifier__preallocated__phrase___code_"/><link + linkend="context.econtext.struct__code__phrase_role__identifier__preallocated__phrase___code_">Struct + <code><phrase role="identifier">preallocated</phrase></code></link> + </bridgehead> +<programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">preallocated</phrase> <phrase role="special">{</phrase> + <phrase role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">;</phrase> + <phrase role="identifier">stack_context</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">;</phrase> + + <phrase role="identifier">preallocated</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">:</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">,</phrase> <phrase role="identifier">stack_allocator</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> +<phrase role="special">};</phrase> +</programlisting> + <bridgehead renderas="sect3" id="context.econtext.h12"> + <phrase id="context.econtext._code__phrase_role__identifier__preallocated__phrase__phrase_role__special_____phrase___phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase___phrase_role__identifier__std__phrase__phrase_role__special_____phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_allocator__phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.econtext._code__phrase_role__identifier__preallocated__phrase__phrase_role__special_____phrase___phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase___phrase_role__identifier__std__phrase__phrase_role__special_____phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_allocator__phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="identifier">preallocated</phrase><phrase role="special">(</phrase> <phrase + role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase + role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">:</phrase><phrase + role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase + role="special">,</phrase> <phrase role="identifier">stack_allocator</phrase> + <phrase role="identifier">sctx</phrase><phrase role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Crreates an object of preallocated. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack"> + <title><link linkend="context.stack">Stack allocation</link></title> + <para> + The memory used by the stack is allocated/deallocated via a <emphasis>StackAllocator</emphasis> + which is required to model a <emphasis>stack-allocator concept</emphasis>. + </para> + <bridgehead renderas="sect3" id="context.stack.h0"> + <phrase id="context.stack._emphasis_stack_allocator_concept__emphasis_"/><link + linkend="context.stack._emphasis_stack_allocator_concept__emphasis_"><emphasis>stack-allocator + concept</emphasis></link> + </bridgehead> + <para> + A <emphasis>StackAllocator</emphasis> must satisfy the <emphasis>stack-allocator + concept</emphasis> requirements shown in the following table, in which <code><phrase + role="identifier">a</phrase></code> is an object of a <emphasis>StackAllocator</emphasis> + type, <code><phrase role="identifier">sctx</phrase></code> is a <code><phrase + role="identifier">stack_context</phrase></code>, and <code><phrase role="identifier">size</phrase></code> + is a <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase + role="identifier">size_t</phrase></code>: + </para> + <informaltable frame="all"> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para> + expression + </para> + </entry> + <entry> + <para> + return type + </para> + </entry> + <entry> + <para> + notes + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code><phrase role="identifier">a</phrase><phrase role="special">(</phrase><phrase + role="identifier">size</phrase><phrase role="special">)</phrase></code> + </para> + </entry> + <entry> + </entry> + <entry> + <para> + creates a stack allocator + </para> + </entry> + </row> + <row> + <entry> + <para> + <code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase + role="identifier">allocate</phrase><phrase role="special">()</phrase></code> + </para> + </entry> + <entry> + <para> + <code><phrase role="identifier">stack_context</phrase></code> + </para> + </entry> + <entry> + <para> + creates a stack + </para> + </entry> + </row> + <row> + <entry> + <para> + <code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase + role="identifier">deallocate</phrase><phrase role="special">(</phrase> + <phrase role="identifier">sctx</phrase><phrase role="special">)</phrase></code> + </para> + </entry> + <entry> + <para> + <code><phrase role="keyword">void</phrase></code> + </para> + </entry> + <entry> + <para> + deallocates the stack created by <code><phrase role="identifier">a</phrase><phrase + role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <important> + <para> + The implementation of <code><phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code> might include logic to protect against + exceeding the context's available stack size rather than leaving it as undefined + behaviour. + </para> + </important> + <important> + <para> + Calling <code><phrase role="identifier">deallocate</phrase><phrase role="special">()</phrase></code> + with a <code><phrase role="identifier">stack_context</phrase></code> not + set by <code><phrase role="identifier">allocate</phrase><phrase role="special">()</phrase></code> + results in undefined behaviour. + </para> + </important> + <note> + <para> + The stack is not required to be aligned; alignment takes place inside <emphasis>execution_context</emphasis>. + </para> + </note> + <note> + <para> + Depending on the architecture <code><phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code> stores an address from the top of the stack + (growing downwards) or the bottom of the stack (growing upwards). + </para> + </note> + <section id="context.stack.protected_fixedsize"> + <title><link linkend="context.stack.protected_fixedsize">Class <emphasis>protected_fixedsize</emphasis></link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> provides the class <emphasis>protected_fixedsize_stack</emphasis> + which models the <emphasis>stack-allocator concept</emphasis>. It appends + a guard page at the end of each stack to protect against exceeding the stack. + If the guard page is accessed (read or write operation) a segmentation fault/access + violation is generated by the operating system. + </para> + <important> + <para> + Using <emphasis>protected_fixedsize_stack</emphasis> is expensive. That + is, launching a new coroutine with a new stack is expensive; the allocated + stack is just as efficient to use as any other stack. + </para> + </important> + <note> + <para> + The appended <code><phrase role="identifier">guard</phrase> <phrase role="identifier">page</phrase></code> + is <emphasis role="bold">not</emphasis> mapped to physical memory, only + virtual addresses are used. + </para> + </note> +<programlisting><phrase role="preprocessor">#include</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">protected_fixedsize</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> + +<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> +<phrase role="keyword">struct</phrase> <phrase role="identifier">basic_protected_fixedsize</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">typedef</phrase> <phrase role="identifier">traitT</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">;</phrase> + + <phrase role="identifier">basic_protected_fixesize</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> + + <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> + + <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> +<phrase role="special">}</phrase> + +<phrase role="keyword">typedef</phrase> <phrase role="identifier">basic_protected_fixedsize</phrase><phrase role="special"><</phrase> <phrase role="identifier">stack_traits</phrase> <phrase role="special">></phrase> <phrase role="identifier">protected_fixedsize</phrase> +</programlisting> + <bridgehead renderas="sect4" id="context.stack.protected_fixedsize.h0"> + <phrase id="context.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code><phrase + role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">minimum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> + and <code><phrase role="special">!</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase + role="special">()</phrase> <phrase role="special">&&</phrase> + <phrase role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">maximum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special">>=</phrase> <phrase + role="identifier">size</phrase><phrase role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Allocates memory of at least <code><phrase role="identifier">size</phrase></code> + Bytes and stores a pointer to the stack and its actual size in <code><phrase + role="identifier">sctx</phrase></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.protected_fixedsize.h1"> + <phrase id="context.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase + role="special">(</phrase> <phrase role="identifier">stack_context</phrase> + <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">minimum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special"><=</phrase> <phrase + role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">size</phrase></code> and <code><phrase role="special">!</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> + <phrase role="special">&&</phrase> <phrase role="special">(</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">maximum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special">>=</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">.</phrase><phrase role="identifier">size</phrase><phrase + role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Deallocates the stack space. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack.fixedsize"> + <title><link linkend="context.stack.fixedsize">Class <emphasis>fixedsize_stack</emphasis></link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> provides the class <emphasis>fixedsize_stack</emphasis> + which models the <emphasis>stack-allocator concept</emphasis>. In contrast + to <emphasis>protected_fixedsize_stack</emphasis> it does not append a guard + page at the end of each stack. The memory is simply managed by <code><phrase + role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">malloc</phrase><phrase + role="special">()</phrase></code> and <code><phrase role="identifier">std</phrase><phrase + role="special">::</phrase><phrase role="identifier">free</phrase><phrase + role="special">()</phrase></code>. + </para> +<programlisting><phrase role="preprocessor">#include</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">fixedsize_stack</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> + +<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> +<phrase role="keyword">struct</phrase> <phrase role="identifier">basic_fixedsize_stack</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">typedef</phrase> <phrase role="identifier">traitT</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">;</phrase> + + <phrase role="identifier">basic_fixesize_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> + + <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> + + <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> +<phrase role="special">}</phrase> + +<phrase role="keyword">typedef</phrase> <phrase role="identifier">basic_fixedsize_stack</phrase><phrase role="special"><</phrase> <phrase role="identifier">stack_traits</phrase> <phrase role="special">></phrase> <phrase role="identifier">fixedsize_stack</phrase><phrase role="special">;</phrase> +</programlisting> + <bridgehead renderas="sect4" id="context.stack.fixedsize.h0"> + <phrase id="context.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code><phrase + role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">minimum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> + and <code><phrase role="special">!</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase + role="special">()</phrase> <phrase role="special">&&</phrase> + <phrase role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">maximum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special">>=</phrase> <phrase + role="identifier">size</phrase><phrase role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Allocates memory of at least <code><phrase role="identifier">size</phrase></code> + Bytes and stores a pointer to the stack and its actual size in <code><phrase + role="identifier">sctx</phrase></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.fixedsize.h1"> + <phrase id="context.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase + role="special">(</phrase> <phrase role="identifier">stack_context</phrase> + <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">minimum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special"><=</phrase> <phrase + role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">size</phrase></code> and <code><phrase role="special">!</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> + <phrase role="special">&&</phrase> <phrase role="special">(</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">maximum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special">>=</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">.</phrase><phrase role="identifier">size</phrase><phrase + role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Deallocates the stack space. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack.segmented"> + <title><link linkend="context.stack.segmented">Class <emphasis>segmented_stack</emphasis></link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> supports usage of a <emphasis>segmented_stack</emphasis>, + e. g. the size of the stack grows on demand. The coroutine is created with + a minimal stack size and will be increased as required. Class <emphasis>segmented_stack</emphasis> + models the <emphasis>stack-allocator concept</emphasis>. In contrast to + <emphasis>protected_fixedsize_stack</emphasis> and <emphasis>fixedsize_stack</emphasis> + it creates a stack which grows on demand. + </para> + <note> + <para> + Segmented stacks are currently only supported by <emphasis role="bold">gcc</emphasis> + from version <emphasis role="bold">4.7</emphasis> <emphasis role="bold">clang</emphasis> + from version <emphasis role="bold">3.4</emphasis> onwards. In order to + use a __segmented_stack__ <emphasis role="bold">Boost.Context</emphasis> + must be built with <emphasis role="bold">toolset=gcc segmented-stacks=on</emphasis> + at b2/bjam command-line. Applications must be compiled with compiler-flags + <emphasis role="bold">-fsplit-stack -DBOOST_USE_SEGMENTED_STACKS</emphasis>. + </para> + </note> +<programlisting><phrase role="preprocessor">#include</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">segmented_stack</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> + +<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> +<phrase role="keyword">struct</phrase> <phrase role="identifier">basic_segmented_stack</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">typedef</phrase> <phrase role="identifier">traitT</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">;</phrase> + + <phrase role="identifier">basic_segmented_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> + + <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> + + <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> +<phrase role="special">}</phrase> + +<phrase role="keyword">typedef</phrase> <phrase role="identifier">basic_segmented_stack</phrase><phrase role="special"><</phrase> <phrase role="identifier">stack_traits</phrase> <phrase role="special">></phrase> <phrase role="identifier">segmented_stack</phrase><phrase role="special">;</phrase> +</programlisting> + <bridgehead renderas="sect4" id="context.stack.segmented.h0"> + <phrase id="context.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code><phrase + role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase + role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">minimum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> + and <code><phrase role="special">!</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase + role="special">()</phrase> <phrase role="special">&&</phrase> + <phrase role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">maximum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special">>=</phrase> <phrase + role="identifier">size</phrase><phrase role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Allocates memory of at least <code><phrase role="identifier">size</phrase></code> + Bytes and stores a pointer to the stack and its actual size in <code><phrase + role="identifier">sctx</phrase></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.segmented.h1"> + <phrase id="context.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"/><link + linkend="context.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code><phrase + role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase + role="special">(</phrase> <phrase role="identifier">stack_context</phrase> + <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">)</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase + role="special">::</phrase><phrase role="identifier">minimum</phrase><phrase + role="special">:</phrase><phrase role="identifier">size</phrase><phrase + role="special">()</phrase> <phrase role="special"><=</phrase> <phrase + role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase + role="identifier">size</phrase></code> and <code><phrase role="special">!</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> + <phrase role="special">&&</phrase> <phrase role="special">(</phrase> + <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase + role="identifier">maximum</phrase><phrase role="special">:</phrase><phrase + role="identifier">size</phrase><phrase role="special">()</phrase> + <phrase role="special">>=</phrase> <phrase role="identifier">sctx</phrase><phrase + role="special">.</phrase><phrase role="identifier">size</phrase><phrase + role="special">)</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effects:</term> + <listitem> + <para> + Deallocates the stack space. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack.stack_traits"> + <title><link linkend="context.stack.stack_traits">Class <emphasis>stack_traits</emphasis></link></title> + <para> + <emphasis>stack_traits</emphasis> models a <emphasis>stack-traits</emphasis> + providing a way to access certain properites defined by the enironment. Stack + allocators use <emphasis>stack-traits</emphasis> to allocate stacks. + </para> +<programlisting><phrase role="preprocessor">#include</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">stack_traits</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> + +<phrase role="keyword">struct</phrase> <phrase role="identifier">stack_traits</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">static</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">page_size</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">default_size</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">minimum_size</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> + + <phrase role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">maximum_size</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + <bridgehead renderas="sect4" id="context.stack.stack_traits.h0"> + <phrase id="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="keyword">bool</phrase> <phrase + role="identifier">is_unbounded</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns <code><phrase role="keyword">true</phrase></code> if the environment + defines no limit for the size of a stack. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.stack_traits.h1"> + <phrase id="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase + role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase + role="identifier">page_size</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns the page size in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.stack_traits.h2"> + <phrase id="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase + role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase + role="identifier">default_size</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns a default stack size, which may be platform specific. If the + stack is unbounded then the present implementation returns the maximum + of <code><phrase role="number">64</phrase> <phrase role="identifier">kB</phrase></code> + and <code><phrase role="identifier">minimum_size</phrase><phrase role="special">()</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.stack_traits.h3"> + <phrase id="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase + role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase + role="identifier">minimum_size</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns the minimum size in bytes of stack defined by the environment + (Win32 4kB/Win64 8kB, defined by rlimit on POSIX). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.stack_traits.h4"> + <phrase id="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"/><link + linkend="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"><code><phrase + role="keyword">static</phrase> <phrase role="identifier">std</phrase><phrase + role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase + role="identifier">maximum_size</phrase><phrase role="special">()</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Preconditions:</term> + <listitem> + <para> + <code><phrase role="identifier">is_unbounded</phrase><phrase role="special">()</phrase></code> + returns <code><phrase role="keyword">false</phrase></code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + Returns the maximum size in bytes of stack defined by the environment. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Throws:</term> + <listitem> + <para> + Nothing. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack.stack_context"> + <title><link linkend="context.stack.stack_context">Class <emphasis>stack_context</emphasis></link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> provides the class <emphasis>stack_context</emphasis> + which will contain the stack pointer and the size of the stack. In case of + a <emphasis>segmented_stack</emphasis>, <emphasis>stack_context</emphasis> + contains some extra control structures. + </para> +<programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">stack_context</phrase> +<phrase role="special">{</phrase> + <phrase role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase><phrase role="special">;</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">;</phrase> + + <phrase role="comment">// might contain additional control structures</phrase> + <phrase role="comment">// for segmented stacks</phrase> +<phrase role="special">}</phrase> +</programlisting> + <bridgehead renderas="sect4" id="context.stack.stack_context.h0"> + <phrase id="context.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"/><link + linkend="context.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"><code><phrase + role="keyword">void</phrase> <phrase role="special">*</phrase> <phrase role="identifier">sp</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Value:</term> + <listitem> + <para> + Pointer to the beginning of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + <bridgehead renderas="sect4" id="context.stack.stack_context.h1"> + <phrase id="context.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"/><link + linkend="context.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"><code><phrase + role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> + <phrase role="identifier">size</phrase></code></link> + </bridgehead> + <variablelist> + <title></title> + <varlistentry> + <term>Value:</term> + <listitem> + <para> + Actual size of the stack. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="context.stack.valgrind"> + <title><link linkend="context.stack.valgrind">Support for valgrind</link></title> + <para> + Running programs that switch stacks under valgrind causes problems. Property + (b2 command-line) <code><phrase role="identifier">valgrind</phrase><phrase + role="special">=</phrase><phrase role="identifier">on</phrase></code> let + valgrind treat the memory regions as stack space which suppresses the errors. + </para> + </section> + </section> + <section id="context.performance"> + <title><link linkend="context.performance">Performance</link></title> + <para> + Performance of <emphasis role="bold">Boost.Context</emphasis> was measured + on the platforms shown in the following table. Performance measurements were + taken using <code><phrase role="identifier">rdtsc</phrase></code> and <code><phrase + role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase + role="special">::</phrase><phrase role="identifier">high_resolution_clock</phrase></code>, + with overhead corrections, on x86 platforms. In each case, cache warm-up was + accounted for, and the one running thread was pinned to a single CPU. The code + was compiled using the build options, 'variant = release cxxflags = -DBOOST_DISABLE_ASSERTS'. + </para> + <table frame="all" id="context.performance.performance_of_context_switch"> + <title>Performance of context switch</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + <para> + Platform + </para> + </entry> + <entry> + <para> + ucontext_t + </para> + </entry> + <entry> + <para> + fcontext_t + </para> + </entry> + <entry> + <para> + windows fibers + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + i386 <footnote id="context.performance.f0"> + <para> + AMD Athlon 64 DualCore 4400+ + </para> + </footnote> + </para> + </entry> + <entry> + <para> + 708 ns / 754 cycles + </para> + </entry> + <entry> + <para> + 37 ns / 37 cycles + </para> + </entry> + <entry> + <para> + ns / cycles + </para> + </entry> + </row> + <row> + <entry> + <para> + x86_64 <footnote id="context.performance.f1"> + <para> + Intel Core2 Q6700 + </para> + </footnote> + </para> + </entry> + <entry> + <para> + 547 ns / 1433 cycles + </para> + </entry> + <entry> + <para> + 8 ns / 23 cycles + </para> + </entry> + <entry> + <para> + ns / cycles + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="context.architectures"> + <title><link linkend="context.architectures">Architectures</link></title> + <para> + <emphasis role="bold">Boost.Context</emphasis> supports following architectures: + </para> + <table frame="all" id="context.architectures.supported_architectures___abi_binary_format__"> + <title>Supported architectures (<ABI|binary format>)</title> + <tgroup cols="5"> + <thead> + <row> + <entry> + <para> + Architecture + </para> + </entry> + <entry> + <para> + LINUX (UNIX) + </para> + </entry> + <entry> + <para> + Windows + </para> + </entry> + <entry> + <para> + MacOS X + </para> + </entry> + <entry> + <para> + iOS + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + arm + </para> + </entry> + <entry> + <para> + AAPCS|ELF + </para> + </entry> + <entry> + <para> + AAPCS|PE + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + AAPCS|MACH-O + </para> + </entry> + </row> + <row> + <entry> + <para> + i386 + </para> + </entry> + <entry> + <para> + SYSV|ELF + </para> + </entry> + <entry> + <para> + MS|PE + </para> + </entry> + <entry> + <para> + SYSV|MACH-O + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + <row> + <entry> + <para> + mips1 + </para> + </entry> + <entry> + <para> + O32|ELF + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + <row> + <entry> + <para> + ppc32 + </para> + </entry> + <entry> + <para> + SYSV|ELF,XCOFF + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + SYSV|MACH-O + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + <row> + <entry> + <para> + ppc64 + </para> + </entry> + <entry> + <para> + SYSV|ELF,XCOFF + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + SYSV|MACH-O + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + <row> + <entry> + <para> + sparc + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + <row> + <entry> + <para> + x86_64 + </para> + </entry> + <entry> + <para> + SYSV,X32|ELF + </para> + </entry> + <entry> + <para> + MS|PE + </para> + </entry> + <entry> + <para> + SYSV|MACH-O + </para> + </entry> + <entry> + <para> + - + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="context.rationale"> + <title><link linkend="context.rationale">Rationale</link></title> + <bridgehead renderas="sect3" id="context.rationale.h0"> + <phrase id="context.rationale.no_inline_assembler"/><link linkend="context.rationale.no_inline_assembler">No + inline-assembler</link> + </bridgehead> + <para> + Some newer compiler (for instance MSVC 10 for x86_64 and itanium) do not support + inline assembler. <footnote id="context.rationale.f0"> + <para> + <ulink url="http://msdn.microsoft.com/en-us/library/4ks26t93.aspx">MSDN article + 'Inline Assembler'</ulink> + </para> + </footnote>. Inlined assembler generates code bloating which his not welcome + on embedded systems. + </para> + <bridgehead renderas="sect3" id="context.rationale.h1"> + <phrase id="context.rationale.fcontext_t"/><link linkend="context.rationale.fcontext_t">fcontext_t</link> + </bridgehead> + <para> + <emphasis role="bold">Boost.Context</emphasis> provides the low level API fcontext_t + which is implemented in assembler to provide context swapping operations. fcontext_t + is the part to port to new platforms. + </para> + <note> + <para> + Context switches do not preserve the signal mask on UNIX systems. + </para> + </note> + <para> + <emphasis>fcontext_t</emphasis> is an opaque pointer. + </para> + <section id="context.rationale.other_apis_"> + <title><link linkend="context.rationale.other_apis_">Other APIs </link></title> + <bridgehead renderas="sect4" id="context.rationale.other_apis_.h0"> + <phrase id="context.rationale.other_apis_.setjmp___longjmp__"/><link linkend="context.rationale.other_apis_.setjmp___longjmp__">setjmp()/longjmp()</link> + </bridgehead> + <para> + C99 defines <code><phrase role="identifier">setjmp</phrase><phrase role="special">()</phrase></code>/<code><phrase + role="identifier">longjmp</phrase><phrase role="special">()</phrase></code> + to provide non-local jumps but it does not require that <emphasis>longjmp()</emphasis> + preserves the current stack frame. Therefore, jumping into a function which + was exited via a call to <emphasis>longjmp()</emphasis> is undefined <footnote + id="context.rationale.other_apis_.f0"> + <para> + ISO/IEC 9899:1999, 2005, 7.13.2.1:2 + </para> + </footnote>. + </para> + <bridgehead renderas="sect4" id="context.rationale.other_apis_.h1"> + <phrase id="context.rationale.other_apis_.ucontext_t"/><link linkend="context.rationale.other_apis_.ucontext_t">ucontext_t</link> + </bridgehead> + <para> + Since POSIX.1-2003 <code><phrase role="identifier">ucontext_t</phrase></code> + is deprecated and was removed in POSIX.1-2008! The function signature of + <code><phrase role="identifier">makecontext</phrase><phrase role="special">()</phrase></code> + is: + </para> +<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">makecontext</phrase><phrase role="special">(</phrase><phrase role="identifier">ucontext_t</phrase> <phrase role="special">*</phrase><phrase role="identifier">ucp</phrase><phrase role="special">,</phrase> <phrase role="keyword">void</phrase> <phrase role="special">(*</phrase><phrase role="identifier">func</phrase><phrase role="special">)(),</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">argc</phrase><phrase role="special">,</phrase> <phrase role="special">...);</phrase> +</programlisting> + <para> + The third argument of <code><phrase role="identifier">makecontext</phrase><phrase + role="special">()</phrase></code> specifies the number of integer arguments + that follow which will require function pointer cast if <code><phrase role="identifier">func</phrase></code> + will accept those arguments which is undefined in C99 <footnote id="context.rationale.other_apis_.f1"> + <para> + ISO/IEC 9899:1999, 2005, J.2 + </para> + </footnote>. + </para> + <para> + The arguments in the var-arg list are required to be integers, passing pointers + in var-arg list is not guaranteed to work, especially it will fail for architectures + where pointers are larger than integers. + </para> + <para> + <code><phrase role="identifier">ucontext_t</phrase></code> preserves signal + mask between context switches which involves system calls consuming a lot + of CPU cycles (ucontext_t is slower by perfomance_link[factor 13x] relative + to <code><phrase role="identifier">fcontext_t</phrase></code>). + </para> + <bridgehead renderas="sect4" id="context.rationale.other_apis_.h2"> + <phrase id="context.rationale.other_apis_.windows_fibers"/><link linkend="context.rationale.other_apis_.windows_fibers">Windows + fibers</link> + </bridgehead> + <para> + A drawback of Windows Fiber API is that <code><phrase role="identifier">CreateFiber</phrase><phrase + role="special">()</phrase></code> does not accept a pointer to user allocated + stack space preventing the reuse of stacks for other context instances. Because + the Windows Fiber API requires to call <code><phrase role="identifier">ConvertThreadToFiber</phrase><phrase + role="special">()</phrase></code> if <code><phrase role="identifier">SwitchFiber</phrase><phrase + role="special">()</phrase></code> is called for a thread which has not been + converted to a fiber. For the same reason <code><phrase role="identifier">ConvertFiberToThread</phrase><phrase + role="special">()</phrase></code> must be called after return from <code><phrase + role="identifier">SwitchFiber</phrase><phrase role="special">()</phrase></code> + if the thread was forced to be converted to a fiber before (which is inefficient). + </para> +<programlisting><phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">is_a_fiber</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> +<phrase role="special">{</phrase> + <phrase role="identifier">ConvertThreadToFiber</phrase><phrase role="special">(</phrase> <phrase role="number">0</phrase><phrase role="special">);</phrase> + <phrase role="identifier">SwitchToFiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">);</phrase> + <phrase role="identifier">ConvertFiberToThread</phrase><phrase role="special">();</phrase> +<phrase role="special">}</phrase> +</programlisting> + <para> + If the condition <code><phrase role="identifier">_WIN32_WINNT</phrase> <phrase + role="special">>=</phrase> <phrase role="identifier">_WIN32_WINNT_VISTA</phrase></code> + is met function <code><phrase role="identifier">IsThreadAFiber</phrase><phrase + role="special">()</phrase></code> is provided in order to detect if the current + thread was already converted. Unfortunately Windows XP + SP 2/3 defines + <code><phrase role="identifier">_WIN32_WINNT</phrase> <phrase role="special">>=</phrase> + <phrase role="identifier">_WIN32_WINNT_VISTA</phrase></code> without providing + <code><phrase role="identifier">IsThreadAFiber</phrase><phrase role="special">()</phrase></code>. + </para> + </section> + <section id="context.rationale.x86_and_floating_point_env"> + <title><link linkend="context.rationale.x86_and_floating_point_env">x86 and + floating-point env</link></title> + <bridgehead renderas="sect4" id="context.rationale.x86_and_floating_point_env.h0"> + <phrase id="context.rationale.x86_and_floating_point_env.i386"/><link linkend="context.rationale.x86_and_floating_point_env.i386">i386</link> + </bridgehead> + <para> + "The FpCsr and the MxCsr register must be saved and restored before + any call or return by any procedure that needs to modify them ..." + <footnote id="context.rationale.x86_and_floating_point_env.f0"> + <para> + 'Calling Conventions', Agner Fog + </para> + </footnote>. + </para> + <bridgehead renderas="sect4" id="context.rationale.x86_and_floating_point_env.h1"> + <phrase id="context.rationale.x86_and_floating_point_env.x86_64"/><link linkend="context.rationale.x86_and_floating_point_env.x86_64">x86_64</link> + </bridgehead> + <bridgehead renderas="sect4" id="context.rationale.x86_and_floating_point_env.h2"> + <phrase id="context.rationale.x86_and_floating_point_env.windows"/><link + linkend="context.rationale.x86_and_floating_point_env.windows">Windows</link> + </bridgehead> + <para> + MxCsr - "A callee that modifies any of the non-volatile fields within + MxCsr must restore them before returning to its caller. Furthermore, a caller + that has modified any of these fields must restore them to their standard + values before invoking a callee ..." <footnote id="context.rationale.x86_and_floating_point_env.f1"> + <para> + <ulink url="http://http://msdn.microsoft.com/en-us/library/yxty7t75.aspx">MSDN + article 'MxCsr'</ulink> + </para> + </footnote>. + </para> + <para> + FpCsr - "A callee that modifies any of the fields within FpCsr must + restore them before returning to its caller. Furthermore, a caller that has + modified any of these fields must restore them to their standard values before + invoking a callee ..." <footnote id="context.rationale.x86_and_floating_point_env.f2"> + <para> + <ulink url="http://http://msdn.microsoft.com/en-us/library/ms235300.aspx">MSDN + article 'FpCsr'</ulink> + </para> + </footnote>. + </para> + <para> + "The MMX and floating-point stack registers (MM0-MM7/ST0-ST7) are preserved + across context switches. There is no explicit calling convention for these + registers." <footnote id="context.rationale.x86_and_floating_point_env.f3"> + <para> + <ulink url="http://msdn.microsoft.com/en-us/library/a32tsf7t%28VS.80%29.aspx">MSDN + article 'Legacy Floating-Point Support'</ulink> + </para> + </footnote>. + </para> + <para> + "The 64-bit Microsoft compiler does not use ST(0)-ST(7)/MM0-MM7". + <footnote id="context.rationale.x86_and_floating_point_env.f4"> + <para> + 'Calling Conventions', Agner Fog + </para> + </footnote>. + </para> + <para> + "XMM6-XMM15 must be preserved" <footnote id="context.rationale.x86_and_floating_point_env.f5"> + <para> + <ulink url="http://msdn.microsoft.com/en-us/library/9z1stfyw%28v=vs.100%29.aspx">MSDN + article 'Register Usage'</ulink> + </para> + </footnote> + </para> + <bridgehead renderas="sect4" id="context.rationale.x86_and_floating_point_env.h3"> + <phrase id="context.rationale.x86_and_floating_point_env.sysv"/><link linkend="context.rationale.x86_and_floating_point_env.sysv">SysV</link> + </bridgehead> + <para> + "The control bits of the MxCsr register are callee-saved (preserved + across calls), while the status bits are caller-saved (not preserved). The + x87 status word register is caller-saved, whereas the x87 control word (FpCsr) + is callee-saved." <footnote id="context.rationale.x86_and_floating_point_env.f6"> + <para> + SysV ABI AMD64 Architecture Processor Supplement Draft Version 0.99.4, + 3.2.1 + </para> + </footnote>. + </para> + </section> + </section> + <section id="context.reference"> + <title><link linkend="context.reference">Reference</link></title> + <bridgehead renderas="sect3" id="context.reference.h0"> + <phrase id="context.reference.arm"/><link linkend="context.reference.arm">ARM</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + AAPCS ABI: Procedure Call Standard for the ARM Architecture + </simpara> + </listitem> + <listitem> + <simpara> + AAPCS/LINUX: ARM GNU/Linux Application Binary Interface Supplement + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect3" id="context.reference.h1"> + <phrase id="context.reference.mips"/><link linkend="context.reference.mips">MIPS</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + O32 ABI: SYSTEM V APPLICATION BINARY INTERFACE, MIPS RISC Processor Supplement + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect3" id="context.reference.h2"> + <phrase id="context.reference.powerpc32"/><link linkend="context.reference.powerpc32">PowerPC32</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE PowerPC Processor Supplement + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect3" id="context.reference.h3"> + <phrase id="context.reference.powerpc64"/><link linkend="context.reference.powerpc64">PowerPC64</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + SYSV ABI: PowerPC User Instruction Set Architecture, Book I + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect3" id="context.reference.h4"> + <phrase id="context.reference.x86_32"/><link linkend="context.reference.x86_32">X86-32</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE, Intel386TM Architecture + Processor Supplement + </simpara> + </listitem> + <listitem> + <simpara> + MS PE: <ulink url="http://msdn.microsoft.com/en-us/library/k2b2ssfy.aspx">Calling + Conventions</ulink> + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect3" id="context.reference.h5"> + <phrase id="context.reference.x86_64"/><link linkend="context.reference.x86_64">X86-64</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + SYSV ABI: System V Application Binary Interface, AMD64 Architecture Processor + Supplement + </simpara> + </listitem> + <listitem> + <simpara> + MS PE: <ulink url="http://msdn.microsoft.com/en-us/library/7kcdt6fy%28VS.80%29.aspx">x64 + Software Conventions</ulink> + </simpara> + </listitem> + </itemizedlist> + </section> + <section id="context.acknowledgements"> + <title><link linkend="context.acknowledgements">Acknowledgments</link></title> + <para> + I'd like to thank Adreas Fett, Artyom Beilis, Daniel Larimer, David Deakins, + Evgeny Shapovalov, Fernando Pelliccioni, Giovanni Piero Deretta, Gordon Woodhull, + Helge Bahmann, Holger Grund, Jeffrey Lee Hellrung (Jr.), Keith Jeffery, Martin + Husemann, Phil Endecott, Robert Stewart, Sergey Cheban, Steven Watanabe, Vicente + J. Botet Escriba, Wayne Piekarski. + </para> + </section> +</library> diff --git a/libs/context/doc/execution_context.qbk b/libs/context/doc/execution_context.qbk new file mode 100644 index 000000000..81535f7aa --- /dev/null +++ b/libs/context/doc/execution_context.qbk @@ -0,0 +1,268 @@ +[/ + Copyright Oliver Kowalke 2014. + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt +] + +[section:econtext Class execution_context] + +[important __econtext__ is supported only by C++14.] + +Class __econtext__ encapsulates __fcontext__ and related functions ( +__jump_fcontext__ and __make_fcontext__) as well as stack management. +__econtext__ permits access to the current, active context via +`execution_context::current()`. + + /* + * grammar: + * P ---> E '\0' + * E ---> T {('+'|'-') T} + * T ---> S {('*'|'/') S} + * S ---> digit | '(' E ')' + */ + class Parser{ + // implementation omitted; see examples directory + }; + + int main() { + std::istringstream is("1+1"); + bool done=false; + char c; + + // create handle to main execution context + boost::context::execution_context main_ctx( + boost::context::execution_context::current() ); + + // executes parser in new execution context + boost::context::execution_context parser_ctx( + boost::context::fixedsize_stack(), + [&main_ctx,&is,&c,&done](){ + // create parser with callback function + Parser p(is, + [&main_ctx,&c](char ch){ + c=ch; + // resume main execution context + main_ctx.resume(); + }); + // start recursive parsing + p.run(); + done=true; + // return to main execution context + main_ctx.resume(); + }); + + // user-code pulls parsed data from parser + // inverted control flow + parser_ctx.resume(); + do { + printf("Parsed: %c\n",c); + parser_ctx.resume(); + } while( ! done); + } + + output: + Parsed: 1 + Parsed: + + Parsed: 1 + + +In this example a recursive descent parser uses a callback to emit a newly passed +symbol. Using __econtext__ 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). + +The interface of __econtext__ does not transfer data. This is not required +because usually sharing data's address (pointer/reference) sufficient. + +If the code executed by __econtext__ emits an exception, `std::terminate()` will +be called. + +[important Do not jump from inside a catch block and than re-throw exceptions in +another execution context.] + +Sometimes it is necessary to unwind the stack of an unfinished context to +destroy local stack variables so they can release allocated resources (RAII +pattern). The user is responsible for this task. + +[heading allocating control strutures on top of stack] +Allocating control structures on top of the stack requires to allocated the +__stack_context__ and create the control structure with placement new before +__econtext__ is created. +[note The user is responsible for destructing the control structure at the top +of the stack.] + + // stack-alloctor used for (de-)allocating stack + fixedsize_stack salloc( 4048); + // allocate stack space + stack_context sctx( salloc.allocate() ); + // reserve space for control structure on top of the stack + void * sp = static_cast< char * >( sctx.sp) - sizeof( my_control_structure); + std::size_t size = sctx.size - sizeof( my_control_structure); + // placement new creates control structure on reserved space + my_control_structure * cs = new ( sp) my_control_structure( sp, size, sctx, salloc); + ... + // destructing the control structure + cs->~my_control_structure(); + ... + struct my_control_structure { + // execution context + execution_context ectx; + + template< typename StackAllocator > + my_control_structure( void * sp, std::size_t size, stack_context sctx, StackAllocator salloc) : + // create execution context + ectx( preallocated( sp, size, sctx), salloc, entry_func) { + } + ... + }; + +[heading exception handling] +If the function executed inside a __econtext__ emitts ans exception, `std::terminate()` is +called - `std::exception_ptr` can used to store exceptions thrown inside the other context. + +[heading parameter passing] +Input and output parameters are transfered via a lambda capture list and references/pointers. + + class X { + private: + int * inp_; + std::string outp_; + std::exception_ptr excptr_; + boost::context::execution_context caller_; + boost::context::execution_context callee_; + + public: + X() : + inp_( nullptr), + outp_(), + excptr_(), + caller_( boost::context::execution_context::current() ), + callee_( boost::context::fixedsize_stack(), + [=] () { + try { + int i = * inp_; + outp_ = boost::lexical_cast< std::string >( i); + caller_.resume(); + } catch (...) { + excptr_ = std::current_exception(); + } + }) + {} + + std::string operator()( int i) { + inp_ = & i; + callee_.resume(); + if ( excptr_) { + std::rethrow_exception( excptr_); + } + return outp_; + } + }; + + int main() { + X x; + std::cout << x( 7) << std::endl; + std::cout << "done" << std::endl; + } + + +[heading Class `execution_context`] + + class execution_context { + public: + static execution_context current() noexcept; + + template< typename StackAlloc, typename Fn > + execution_context( StackAlloc salloc, Fn && fn); + + template< typename StackAlloc, typename Fn, typename ... Args > + execution_context( StackAlloc salloc, Fn && fn, Args && ... args); + + template< typename StackAlloc, typename Fn > + execution_context( preallocated palloc, StackAlloc salloc, Fn && fn); + + template< typename StackAlloc, typename Fn, typename ... Args > + execution_context( preallocated palloc, StackAlloc salloc, Fn && fn, Args && ... args); + + void resume() noexcept; + + explicit operator bool() const noexcept; + + bool operator!() const noexcept; + }; + +[heading `static execution_context current()`] +[variablelist +[[Returns:] [Returns an instance of excution_context pointing to the active +execution context.]] +[[Throws:] [Nothing.]] +] + +[heading `template< typename StackAlloc, typname Fn > execution_context( StackAlloc salloc, Fn && fn)`] +[variablelist +[[Effects:] [Creates a new execution context and prepares the context to execute +`fn`.]] +] + +[heading `template< typename StackAlloc, typname Fn, typename ... Args > execution_context( StackAlloc salloc, Fn && fn, Args && ... args)`] +[variablelist +[[Effects:] [Creates a new execution context and prepares the context to execute +`fn`.]] +] + +[heading `template< typename StackAlloc, typname Fn > execution_context( preallocated palloc, StackAlloc salloc, Fn && fn)`] +[variablelist +[[Effects:] [Creates a new execution context and prepares the context to execute +`fn`. Used to store control structures on top of the stack.]] +] + +[heading `template< typename StackAlloc, typname Fn, typename ... Args > execution_context( preallocated palloc, StackAlloc salloc, Fn && fn, Args && ... args)`] +[variablelist +[[Effects:] [Creates a new execution context and prepares the context to execute +`fn`. Used to store control structures on top of the stack.]] +] + +[heading `void resume()`] +[variablelist +[[Effects:] [Stores internally the current context data (stack pointer, +instruction pointer, and CPU registers) to the current active context and +restores the context data from `*this`, which implies jumping to `*this`'s +execution context.]] +[[Note:] [The behaviour is undefined if `resume()` is called while `execution_context::current()` +returns `*this` (e.g. resuming an alredy running cotnext).]] +[[Throws:] [Nothing.]] +] + +[heading `explicit operator bool() const`] +[variablelist +[[Returns:] [If `*this` refers to an invalid context or the context-function +has returned (completed), the function returns `false`. Otherwise `true`.]] +[[Throws:] [Nothing.]] +] + +[heading `bool operator!() const`] +[variablelist +[[Returns:] [If `*this` refers to an invalid context or the context-function +has returned (completed), the function returns `true`. Otherwise `false`.]] +[[Throws:] [Nothing.]] +] + + +[heading Struct `preallocated`] + + struct preallocated { + void * sp; + std::size_t size; + stack_context sctx; + + preallocated( void * sp, std:size_t size, stack_allocator sctx) noexcept; + }; + +[heading `preallocated( void * sp, std:size_t size, stack_allocator sctx)`] +[variablelist +[[Effects:] [Crreates an object of preallocated.]] +] + + +[endsect] diff --git a/libs/context/doc/fcontext.qbk b/libs/context/doc/fcontext.qbk index fd09da486..5e1a720eb 100644 --- a/libs/context/doc/fcontext.qbk +++ b/libs/context/doc/fcontext.qbk @@ -1,11 +1,11 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ] -[section:context Context] +[section:context Struct fcontext_t] Each instance of __fcontext__ represents a context (CPU registers and stack space). Together with its related functions __jump_fcontext__ and @@ -70,7 +70,6 @@ new state of the original context. BOOST_ASSERT(false&&!"f2: never returns"); } - boost::context::guarded_stack_allocator alloc; std::size_t size(8192); void* sp1(std::malloc(size)); void* sp2(std::malloc(size)); @@ -125,9 +124,8 @@ other context. boost::context::jump_fcontext(&fc,fcm,(intptr_t)(p->first+p->second)); } - boost::context::guarded_stack_allocator alloc; std::size_t size(8192); - void* sp(size); + void* sp(std::malloc(size)); pair_t p(std::make_pair(2,7)); fc=boost::context::make_fcontext(sp,size,f); @@ -171,7 +169,7 @@ destroy local stack variables so they can release allocated resources (RAII pattern). The user is responsible for this task. -[section:boost_fcontext `fcontext_t` and related functions] +[heading `fcontext_t` and related functions] struct stack_t { @@ -222,5 +220,3 @@ to execute the __context_fn__ `fn`.]] ] [endsect] - -[endsect] diff --git a/libs/context/doc/html/context/acknowledgements.html b/libs/context/doc/html/context/acknowledgements.html index d66de0837..3bc4f758a 100644 --- a/libs/context/doc/html/context/acknowledgements.html +++ b/libs/context/doc/html/context/acknowledgements.html @@ -35,7 +35,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/architectures.html b/libs/context/doc/html/context/architectures.html index 0b126c80b..7712f11f2 100644 --- a/libs/context/doc/html/context/architectures.html +++ b/libs/context/doc/html/context/architectures.html @@ -263,7 +263,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/context.html b/libs/context/doc/html/context/context.html index f3c1f5721..f8f23b66c 100644 --- a/libs/context/doc/html/context/context.html +++ b/libs/context/doc/html/context/context.html @@ -1,13 +1,13 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<title>Context</title> +<title>Struct fcontext_t</title> <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="Chapter 1. Context"> <link rel="up" href="../index.html" title="Chapter 1. Context"> <link rel="prev" href="requirements.html" title="Requirements"> -<link rel="next" href="context/boost_fcontext.html" title="fcontext_t and related functions"> +<link rel="next" href="econtext.html" title="Class execution_context"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> @@ -20,14 +20,12 @@ </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="context/boost_fcontext.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +<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="econtext.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.context"></a><a class="link" href="context.html" title="Context">Context</a> +<a name="context.context"></a><a class="link" href="context.html" title="Struct fcontext_t">Struct fcontext_t</a> </h2></div></div></div> -<div class="toc"><dl class="toc"><dt><span class="section"><a href="context/boost_fcontext.html"><code class="computeroutput"><span class="identifier">fcontext_t</span></code> - and related functions</a></span></dt></dl></div> <p> Each instance of <span class="emphasis"><em>fcontext_t</em></span> represents a context (CPU registers and stack space). Together with its related functions <span class="emphasis"><em>jump_fcontext()</em></span> @@ -117,7 +115,6 @@ <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">&&!</span><span class="string">"f2: never returns"</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">guarded_stack_allocator</span> <span class="identifier">alloc</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="number">8192</span><span class="special">);</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp1</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp2</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span> @@ -198,9 +195,8 @@ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&</span><span class="identifier">fc</span><span class="special">,</span><span class="identifier">fcm</span><span class="special">,(</span><span class="identifier">intptr_t</span><span class="special">)(</span><span class="identifier">p</span><span class="special">-></span><span class="identifier">first</span><span class="special">+</span><span class="identifier">p</span><span class="special">-></span><span class="identifier">second</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">guarded_stack_allocator</span> <span class="identifier">alloc</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="number">8192</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">size</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">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span> <span class="identifier">pair_t</span> <span class="identifier">p</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="number">7</span><span class="special">));</span> <span class="identifier">fc</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">make_fcontext</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">f</span><span class="special">);</span> @@ -275,10 +271,120 @@ local stack variables so they can release allocated resources (RAII pattern). The user is responsible for this task. </p> +<h4> +<a name="context.context.h5"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"><code class="computeroutput"><span class="identifier">fcontext_t</span></code> and related functions</a> + </h4> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">stack_t</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="special">};</span> + +<span class="keyword">typedef</span> <span class="special"><</span><span class="identifier">opaque</span> <span class="identifier">pointer</span> <span class="special">></span> <span class="identifier">fcontext_t</span><span class="special">;</span> + +<span class="identifier">intptr_t</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="identifier">intptr_t</span> <span class="identifier">vp</span><span class="special">,</span><span class="keyword">bool</span> <span class="identifier">preserve_fpu</span><span class="special">=</span><span class="keyword">true</span><span class="special">);</span> +<span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</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="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="identifier">intptr_t</span><span class="special">));</span> +</pre> +<h4> +<a name="context.context.h6"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="identifier">sp</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Member:</span></dt> +<dd><p> + Pointer to the beginning of the stack (depending of the architecture + the stack grows downwards or upwards). + </p></dd> +</dl> +</div> +<h4> +<a name="context.context.h7"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">size</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Member:</span></dt> +<dd><p> + Size of the stack in bytes. + </p></dd> +</dl> +</div> +<h4> +<a name="context.context.h8"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__fc_stack__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fc_stack__phrase___code_"><code class="computeroutput"><span class="identifier">fc_stack</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Member:</span></dt> +<dd><p> + Tracks the memory for the context's stack. + </p></dd> +</dl> +</div> +<h4> +<a name="context.context.h9"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="identifier">intptr_t</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="identifier">intptr_t</span> <span class="identifier">p</span><span class="special">,</span><span class="keyword">bool</span> + <span class="identifier">preserve_fpu</span><span class="special">=</span><span class="keyword">true</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Stores the current context data (stack pointer, instruction pointer, + and CPU registers) to <code class="computeroutput"><span class="special">*</span><span class="identifier">ofc</span></code> and restores the context data from + <code class="computeroutput"><span class="identifier">nfc</span></code>, which implies jumping + to <code class="computeroutput"><span class="identifier">nfc</span></code>'s execution context. + The intptr_t argument, <code class="computeroutput"><span class="identifier">p</span></code>, + is passed to the current context to be returned by the most recent call + to <code class="computeroutput"><span class="identifier">jump_fcontext</span><span class="special">()</span></code> + in the same thread. The last argument controls if fpu registers have + to be preserved. + </p></dd> +<dt><span class="term">Returns:</span></dt> +<dd><p> + The third pointer argument passed to the most recent call to <code class="computeroutput"><span class="identifier">jump_fcontext</span><span class="special">()</span></code>, + if any. + </p></dd> +</dl> +</div> +<h4> +<a name="context.context.h10"></a> + <span class="phrase"><a name="context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</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="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="identifier">intptr_t</span><span class="special">))</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Precondition:</span></dt> +<dd><p> + Stack <code class="computeroutput"><span class="identifier">sp</span></code> and function + pointer <code class="computeroutput"><span class="identifier">fn</span></code> are valid + (depending on the architecture <code class="computeroutput"><span class="identifier">sp</span></code> + points to the top or bottom of the stack) and <code class="computeroutput"><span class="identifier">size</span></code> + > 0. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Creates an fcontext_t on top of the stack and prepares the stack to execute + the <span class="emphasis"><em>context-function</em></span> <code class="computeroutput"><span class="identifier">fn</span></code>. + </p></dd> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns a fcontext_t which is placed on the stack. + </p></dd> +</dl> +</div> </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> @@ -286,7 +392,7 @@ </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="context/boost_fcontext.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +<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="econtext.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/context/doc/html/context/context/boost_fcontext.html b/libs/context/doc/html/context/context/boost_fcontext.html index 961d842d8..8afc10db0 100644 --- a/libs/context/doc/html/context/context/boost_fcontext.html +++ b/libs/context/doc/html/context/context/boost_fcontext.html @@ -3,11 +3,11 @@ <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>fcontext_t and related functions</title> <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> <link rel="home" href="../../index.html" title="Chapter 1. Context"> -<link rel="up" href="../context.html" title="Context"> -<link rel="prev" href="../context.html" title="Context"> -<link rel="next" href="../performance.html" title="Performance"> +<link rel="up" href="../context.html" title="Struct fcontext_t"> +<link rel="prev" href="../context.html" title="Struct fcontext_t"> +<link rel="next" href="../econtext.html" title="Class execution_context"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> @@ -20,7 +20,7 @@ </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="../context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../context.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="../performance.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="../context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../context.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="../econtext.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> @@ -40,11 +40,11 @@ </pre> <h5> <a name="context.context.boost_fcontext.h0"></a> - <span class="phrase"><a name="context.context.boost_fcontext._code__phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="identifier">sp</span></code></a> + <span><a name="context.context.boost_fcontext._code__phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="identifier">sp</span></code></a> </h5> <div class="variablelist"> <p class="title"><b></b></p> -<dl class="variablelist"> +<dl> <dt><span class="term">Member:</span></dt> <dd><p> Pointer to the beginning of the stack (depending of the architecture @@ -54,11 +54,11 @@ </div> <h5> <a name="context.context.boost_fcontext.h1"></a> - <span class="phrase"><a name="context.context.boost_fcontext._code__phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">size</span></code></a> + <span><a name="context.context.boost_fcontext._code__phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">size</span></code></a> </h5> <div class="variablelist"> <p class="title"><b></b></p> -<dl class="variablelist"> +<dl> <dt><span class="term">Member:</span></dt> <dd><p> Size of the stack in bytes. @@ -67,11 +67,11 @@ </div> <h5> <a name="context.context.boost_fcontext.h2"></a> - <span class="phrase"><a name="context.context.boost_fcontext._code__phrase_role__identifier__fc_stack__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__fc_stack__phrase___code_"><code class="computeroutput"><span class="identifier">fc_stack</span></code></a> + <span><a name="context.context.boost_fcontext._code__phrase_role__identifier__fc_stack__phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__fc_stack__phrase___code_"><code class="computeroutput"><span class="identifier">fc_stack</span></code></a> </h5> <div class="variablelist"> <p class="title"><b></b></p> -<dl class="variablelist"> +<dl> <dt><span class="term">Member:</span></dt> <dd><p> Tracks the memory for the context's stack. @@ -80,12 +80,12 @@ </div> <h5> <a name="context.context.boost_fcontext.h3"></a> - <span class="phrase"><a name="context.context.boost_fcontext._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="identifier">intptr_t</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="identifier">intptr_t</span> <span class="identifier">p</span><span class="special">,</span><span class="keyword">bool</span> + <span><a name="context.context.boost_fcontext._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__identifier__intptr_t__phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase__phrase_role__keyword__bool__phrase___phrase_role__identifier__preserve_fpu__phrase__phrase_role__special_____phrase__phrase_role__keyword__true__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="identifier">intptr_t</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="identifier">intptr_t</span> <span class="identifier">p</span><span class="special">,</span><span class="keyword">bool</span> <span class="identifier">preserve_fpu</span><span class="special">=</span><span class="keyword">true</span><span class="special">)</span></code></a> </h5> <div class="variablelist"> <p class="title"><b></b></p> -<dl class="variablelist"> +<dl> <dt><span class="term">Effects:</span></dt> <dd><p> Stores the current context data (stack pointer, instruction pointer, @@ -106,13 +106,13 @@ </div> <h5> <a name="context.context.boost_fcontext.h4"></a> - <span class="phrase"><a name="context.context.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> + <span><a name="context.context.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="boost_fcontext.html#context.context.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__identifier__intptr_t__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</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="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="identifier">intptr_t</span><span class="special">))</span></code></a> </h5> <div class="variablelist"> <p class="title"><b></b></p> -<dl class="variablelist"> +<dl> <dt><span class="term">Precondition:</span></dt> <dd><p> Stack <code class="computeroutput"><span class="identifier">sp</span></code> and function @@ -135,7 +135,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> @@ -143,7 +143,7 @@ </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="../context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../context.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="../performance.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="../context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../context.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="../econtext.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/context/doc/html/context/econtext.html b/libs/context/doc/html/context/econtext.html new file mode 100644 index 000000000..e1452a93b --- /dev/null +++ b/libs/context/doc/html/context/econtext.html @@ -0,0 +1,458 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class execution_context</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Chapter 1. Context"> +<link rel="up" href="../index.html" title="Chapter 1. Context"> +<link rel="prev" href="context.html" title="Struct fcontext_t"> +<link rel="next" href="stack.html" title="Stack allocation"> +</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="context.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="stack.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.econtext"></a><a class="link" href="econtext.html" title="Class execution_context">Class execution_context</a> +</h2></div></div></div> +<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> + <span class="emphasis"><em>execution_context</em></span> is supported only by C++14. + </p></td></tr> +</table></div> +<p> + Class <span class="emphasis"><em>execution_context</em></span> encapsulates <span class="emphasis"><em>fcontext_t</em></span> + and related functions ( <span class="emphasis"><em>jump_fcontext()</em></span> and <span class="emphasis"><em>make_fcontext()</em></span>) + as well as stack management. <span class="emphasis"><em>execution_context</em></span> permits + access to the current, active context via <code class="computeroutput"><span class="identifier">execution_context</span><span class="special">::</span><span class="identifier">current</span><span class="special">()</span></code>. + </p> +<pre class="programlisting"><span class="comment">/* + * grammar: + * P ---> E '\0' + * E ---> T {('+'|'-') T} + * T ---> S {('*'|'/') S} + * S ---> digit | '(' E ')' + */</span> +<span class="keyword">class</span> <span class="identifier">Parser</span><span class="special">{</span> + <span class="comment">// implementation omitted; see examples directory</span> +<span class="special">};</span> + +<span class="keyword">int</span> <span class="identifier">main</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="keyword">bool</span> <span class="identifier">done</span><span class="special">=</span><span class="keyword">false</span><span class="special">;</span> + <span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> + + <span class="comment">// create handle to main execution context</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="identifier">main_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">execution_context</span><span class="special">::</span><span class="identifier">current</span><span class="special">()</span> <span class="special">);</span> + + <span class="comment">// executes parser in new execution context</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="identifier">parser_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">fixedsize_stack</span><span class="special">(),</span> + <span class="special">[&</span><span class="identifier">main_ctx</span><span class="special">,&</span><span class="identifier">is</span><span class="special">,&</span><span class="identifier">c</span><span class="special">,&</span><span class="identifier">done</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">[&</span><span class="identifier">main_ctx</span><span class="special">,&</span><span class="identifier">c</span><span class="special">](</span><span class="keyword">char</span> <span class="identifier">ch</span><span class="special">){</span> + <span class="identifier">c</span><span class="special">=</span><span class="identifier">ch</span><span class="special">;</span> + <span class="comment">// resume main execution context</span> + <span class="identifier">main_ctx</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="identifier">done</span><span class="special">=</span><span class="keyword">true</span><span class="special">;</span> + <span class="comment">// return to main execution context</span> + <span class="identifier">main_ctx</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span> + <span class="special">});</span> + + <span class="comment">// user-code pulls parsed data from parser</span> + <span class="comment">// inverted control flow</span> + <span class="identifier">parser_ctx</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span> + <span class="keyword">do</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">parser_ctx</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span> + <span class="special">}</span> <span class="keyword">while</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">done</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 <span class="emphasis"><em>execution_context</em></span> 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 interface of <span class="emphasis"><em>execution_context</em></span> does not transfer data. + This is not required because usually sharing data's address (pointer/reference) + sufficient. + </p> +<p> + If the code executed by <span class="emphasis"><em>execution_context</em></span> emits an exception, + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span><span class="special">()</span></code> + will be called. + </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 than re-throw exceptions in another + execution context. + </p></td></tr> +</table></div> +<p> + Sometimes it is necessary to unwind the stack of an unfinished context to destroy + local stack variables so they can release allocated resources (RAII pattern). + The user is responsible for this task. + </p> +<h4> +<a name="context.econtext.h0"></a> + <span class="phrase"><a name="context.econtext.allocating_control_strutures_on_top_of_stack"></a></span><a class="link" href="econtext.html#context.econtext.allocating_control_strutures_on_top_of_stack">allocating + control strutures 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 <span class="emphasis"><em>execution_context</em></span> 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="comment">// stack-alloctor 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="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"><</span> <span class="keyword">char</span> <span class="special">*</span> <span class="special">>(</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span><span class="special">)</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">->~</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">// execution context</span> + <span class="identifier">execution_context</span> <span class="identifier">ectx</span><span class="special">;</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAllocator</span> <span class="special">></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 execution context</span> + <span class="identifier">ectx</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.econtext.h1"></a> + <span class="phrase"><a name="context.econtext.exception_handling"></a></span><a class="link" href="econtext.html#context.econtext.exception_handling">exception + handling</a> + </h4> +<p> + If the function executed inside a <span class="emphasis"><em>execution_context</em></span> emitts + ans exception, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span><span class="special">()</span></code> + is called - <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception_ptr</span></code> can used to store exceptions + thrown inside the other context. + </p> +<h4> +<a name="context.econtext.h2"></a> + <span class="phrase"><a name="context.econtext.parameter_passing"></a></span><a class="link" href="econtext.html#context.econtext.parameter_passing">parameter + passing</a> + </h4> +<p> + Input and output parameters are transfered via a lambda capture list and references/pointers. + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{</span> +<span class="keyword">private</span><span class="special">:</span> + <span class="keyword">int</span> <span class="special">*</span> <span class="identifier">inp_</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">outp_</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception_ptr</span> <span class="identifier">excptr_</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="identifier">caller_</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="identifier">callee_</span><span class="special">;</span> + +<span class="keyword">public</span><span class="special">:</span> + <span class="identifier">X</span><span class="special">()</span> <span class="special">:</span> + <span class="identifier">inp_</span><span class="special">(</span> <span class="keyword">nullptr</span><span class="special">),</span> + <span class="identifier">outp_</span><span class="special">(),</span> + <span class="identifier">excptr_</span><span class="special">(),</span> + <span class="identifier">caller_</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">::</span><span class="identifier">current</span><span class="special">()</span> <span class="special">),</span> + <span class="identifier">callee_</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">fixedsize_stack</span><span class="special">(),</span> + <span class="special">[=]</span> <span class="special">()</span> <span class="special">{</span> + <span class="keyword">try</span> <span class="special">{</span> + <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">*</span> <span class="identifier">inp_</span><span class="special">;</span> + <span class="identifier">outp_</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special"><</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">>(</span> <span class="identifier">i</span><span class="special">);</span> + <span class="identifier">caller_</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="special">{</span> + <span class="identifier">excptr_</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">current_exception</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">string</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> + <span class="identifier">inp_</span> <span class="special">=</span> <span class="special">&</span> <span class="identifier">i</span><span class="special">;</span> + <span class="identifier">callee_</span><span class="special">.</span><span class="identifier">resume</span><span class="special">();</span> + <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">excptr_</span><span class="special">)</span> <span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">rethrow_exception</span><span class="special">(</span> <span class="identifier">excptr_</span><span class="special">);</span> + <span class="special">}</span> + <span class="keyword">return</span> <span class="identifier">outp_</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> + <span class="identifier">X</span> <span class="identifier">x</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">x</span><span class="special">(</span> <span class="number">7</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"done"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<h4> +<a name="context.econtext.h3"></a> + <span class="phrase"><a name="context.econtext.class__code__phrase_role__identifier__execution_context__phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext.class__code__phrase_role__identifier__execution_context__phrase___code_">Class + <code class="computeroutput"><span class="identifier">execution_context</span></code></a> + </h4> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">execution_context</span> <span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">execution_context</span> <span class="identifier">current</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span> + <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</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">Args</span> <span class="special">></span> + <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">Args</span> <span class="special">&&</span> <span class="special">...</span> <span class="identifier">args</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span> + <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">preallocated</span> <span class="identifier">palloc</span><span class="special">,</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</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">Args</span> <span class="special">></span> + <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">preallocated</span> <span class="identifier">palloc</span><span class="special">,</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">Args</span> <span class="special">&&</span> <span class="special">...</span> <span class="identifier">args</span><span class="special">);</span> + + <span class="keyword">void</span> <span class="identifier">resume</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">explicit</span> <span class="keyword">operator</span> <span class="keyword">bool</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> +<span class="special">};</span> +</pre> +<h4> +<a name="context.econtext.h4"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__static__phrase___phrase_role__identifier__execution_context__phrase___phrase_role__identifier__current__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__static__phrase___phrase_role__identifier__execution_context__phrase___phrase_role__identifier__current__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">execution_context</span> + <span class="identifier">current</span><span class="special">()</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns an instance of excution_context pointing to the active execution + context. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h5"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="identifier">typname</span> <span class="identifier">Fn</span> <span class="special">></span> <span class="identifier">execution_context</span><span class="special">(</span> + <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> + <span class="identifier">fn</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Creates a new execution context and prepares the context to execute + <code class="computeroutput"><span class="identifier">fn</span></code>. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h6"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="identifier">typname</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">typename</span> + <span class="special">...</span> <span class="identifier">Args</span> + <span class="special">></span> <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">Args</span> + <span class="special">&&</span> <span class="special">...</span> + <span class="identifier">args</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Creates a new execution context and prepares the context to execute + <code class="computeroutput"><span class="identifier">fn</span></code>. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h7"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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___code_"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="identifier">typname</span> <span class="identifier">Fn</span> <span class="special">></span> <span class="identifier">execution_context</span><span class="special">(</span> + <span class="identifier">preallocated</span> <span class="identifier">palloc</span><span class="special">,</span> <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Creates a new execution context and prepares the context to execute + <code class="computeroutput"><span class="identifier">fn</span></code>. Used to store control + structures on top of the stack. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h8"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__template__phrase__phrase_role__special___lt___phrase___phrase_role__keyword__typename__phrase___phrase_role__identifier__stackalloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__typname__phrase___phrase_role__identifier__fn__phrase__phrase_role__special_____phrase___phrase_role__keyword__typename__phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase___phrase_role__special___gt___phrase___phrase_role__identifier__execution_context__phrase__phrase_role__special_____phrase___phrase_role__identifier__preallocated__phrase___phrase_role__identifier__palloc__phrase__phrase_role__special_____phrase___phrase_role__identifier__stackalloc__phrase___phrase_role__identifier__salloc__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__args__phrase___phrase_role__special___amp__amp___phrase___phrase_role__special_______phrase___phrase_role__identifier__args__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">StackAlloc</span><span class="special">,</span> <span class="identifier">typname</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">typename</span> + <span class="special">...</span> <span class="identifier">Args</span> + <span class="special">></span> <span class="identifier">execution_context</span><span class="special">(</span> <span class="identifier">preallocated</span> + <span class="identifier">palloc</span><span class="special">,</span> + <span class="identifier">StackAlloc</span> <span class="identifier">salloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> + <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">Args</span> <span class="special">&&</span> + <span class="special">...</span> <span class="identifier">args</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Creates a new execution context and prepares the context to execute + <code class="computeroutput"><span class="identifier">fn</span></code>. Used to store control + structures on top of the stack. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h9"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__void__phrase___phrase_role__identifier__resume__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__void__phrase___phrase_role__identifier__resume__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">resume</span><span class="special">()</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Stores internally the current context data (stack pointer, instruction + pointer, and CPU registers) to the current active context and restores + the context data from <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>, which implies jumping to <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>'s + execution context. + </p></dd> +<dt><span class="term">Note:</span></dt> +<dd><p> + The behaviour is undefined if <code class="computeroutput"><span class="identifier">resume</span><span class="special">()</span></code> is called while <code class="computeroutput"><span class="identifier">execution_context</span><span class="special">::</span><span class="identifier">current</span><span class="special">()</span></code> returns <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> (e.g. resuming an alredy running + cotnext). + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h10"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__explicit__phrase___phrase_role__keyword__operator__phrase___phrase_role__keyword__bool__phrase__phrase_role__special______phrase___phrase_role__keyword__const__phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__explicit__phrase___phrase_role__keyword__operator__phrase___phrase_role__keyword__bool__phrase__phrase_role__special______phrase___phrase_role__keyword__const__phrase___code_"><code class="computeroutput"><span class="keyword">explicit</span> <span class="keyword">operator</span> + <span class="keyword">bool</span><span class="special">()</span> <span class="keyword">const</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + If <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + refers to an invalid context or the context-function has returned (completed), + the function returns <code class="computeroutput"><span class="keyword">false</span></code>. + Otherwise <code class="computeroutput"><span class="keyword">true</span></code>. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h11"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__keyword__bool__phrase___phrase_role__keyword__operator__phrase__phrase_role__special_______phrase___phrase_role__keyword__const__phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__keyword__bool__phrase___phrase_role__keyword__operator__phrase__phrase_role__special_______phrase___phrase_role__keyword__const__phrase___code_"><code class="computeroutput"><span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!()</span> <span class="keyword">const</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + If <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + refers to an invalid context or the context-function has returned (completed), + the function returns <code class="computeroutput"><span class="keyword">true</span></code>. + Otherwise <code class="computeroutput"><span class="keyword">false</span></code>. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h4> +<a name="context.econtext.h12"></a> + <span class="phrase"><a name="context.econtext.struct__code__phrase_role__identifier__preallocated__phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext.struct__code__phrase_role__identifier__preallocated__phrase___code_">Struct + <code class="computeroutput"><span class="identifier">preallocated</span></code></a> + </h4> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">preallocated</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">preallocated</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_allocator</span> <span class="identifier">sctx</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span> +<span class="special">};</span> +</pre> +<h4> +<a name="context.econtext.h13"></a> + <span class="phrase"><a name="context.econtext._code__phrase_role__identifier__preallocated__phrase__phrase_role__special_____phrase___phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase___phrase_role__identifier__std__phrase__phrase_role__special_____phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_allocator__phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="econtext.html#context.econtext._code__phrase_role__identifier__preallocated__phrase__phrase_role__special_____phrase___phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase___phrase_role__identifier__std__phrase__phrase_role__special_____phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_allocator__phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="identifier">preallocated</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_allocator</span> + <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h4> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Crreates an object of preallocated. + </p></dd> +</dl> +</div> +</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 © 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="context.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="stack.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/acknowledgements.html b/libs/context/doc/html/context/econtext/acknowledgements.html new file mode 100644 index 000000000..e9a60c988 --- /dev/null +++ b/libs/context/doc/html/context/econtext/acknowledgements.html @@ -0,0 +1,49 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Acknowledgments</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="reference.html" title="Reference"> +</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="reference.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.acknowledgements"></a><a class="link" href="acknowledgements.html" title="Acknowledgments">Acknowledgments</a> +</h3></div></div></div> +<p> + I'd like to thank Adreas Fett, Artyom Beilis, Daniel Larimer, David Deakins, + Evgeny Shapovalov, Fernando Pelliccioni, Giovanni Piero Deretta, Gordon Woodhull, + Helge Bahmann, Holger Grund, Jeffrey Lee Hellrung (Jr.), Keith Jeffery, Martin + Husemann, Phil Endecott, Robert Stewart, Sergey Cheban, Steven Watanabe, + Vicente J. Botet Escriba, Wayne Piekarski. + </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 © 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="reference.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/architectures.html b/libs/context/doc/html/context/econtext/architectures.html new file mode 100644 index 000000000..201d252be --- /dev/null +++ b/libs/context/doc/html/context/econtext/architectures.html @@ -0,0 +1,277 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Architectures</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="performance.html" title="Performance"> +<link rel="next" href="rationale.html" title="Rationale"> +</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="performance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="rationale.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.architectures"></a><a class="link" href="architectures.html" title="Architectures">Architectures</a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> supports following architectures: + </p> +<div class="table"> +<a name="context.econtext.architectures.supported_architectures___abi_binary_format__"></a><p class="title"><b>Table 1.2. Supported architectures (<ABI|binary format>)</b></p> +<div class="table-contents"><table class="table" summary="Supported architectures (<ABI|binary format>)"> +<colgroup> +<col> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Architecture + </p> + </th> +<th> + <p> + LINUX (UNIX) + </p> + </th> +<th> + <p> + Windows + </p> + </th> +<th> + <p> + MacOS X + </p> + </th> +<th> + <p> + iOS + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + arm + </p> + </td> +<td> + <p> + AAPCS|ELF + </p> + </td> +<td> + <p> + AAPCS|PE + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + AAPCS|MACH-O + </p> + </td> +</tr> +<tr> +<td> + <p> + i386 + </p> + </td> +<td> + <p> + SYSV|ELF + </p> + </td> +<td> + <p> + MS|PE + </p> + </td> +<td> + <p> + SYSV|MACH-O + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +<tr> +<td> + <p> + mips1 + </p> + </td> +<td> + <p> + O32|ELF + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +<tr> +<td> + <p> + ppc32 + </p> + </td> +<td> + <p> + SYSV|ELF,XCOFF + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + SYSV|MACH-O + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +<tr> +<td> + <p> + ppc64 + </p> + </td> +<td> + <p> + SYSV|ELF,XCOFF + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + SYSV|MACH-O + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +<tr> +<td> + <p> + sparc + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + - + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +<tr> +<td> + <p> + x86_64 + </p> + </td> +<td> + <p> + SYSV,X32|ELF + </p> + </td> +<td> + <p> + MS|PE + </p> + </td> +<td> + <p> + SYSV|MACH-O + </p> + </td> +<td> + <p> + - + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<br class="table-break"> +</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 © 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="performance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="rationale.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/performance.html b/libs/context/doc/html/context/econtext/performance.html new file mode 100644 index 000000000..9dbe3c8c1 --- /dev/null +++ b/libs/context/doc/html/context/econtext/performance.html @@ -0,0 +1,139 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Performance</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="stack/stack_context.html" title="Class stack_context"> +<link rel="next" href="architectures.html" title="Architectures"> +</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="stack/stack_context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="architectures.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.performance"></a><a class="link" href="performance.html" title="Performance">Performance</a> +</h3></div></div></div> +<p> + Performance of <span class="bold"><strong>Boost.Context</strong></span> was measured + on the platforms shown in the following table. Performance measurements were + taken using <code class="computeroutput"><span class="identifier">rdtsc</span></code> and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">high_resolution_clock</span></code>, with overhead corrections, + on x86 platforms. In each case, cache warm-up was accounted for, and the + one running thread was pinned to a single CPU. The code was compiled using + the build options, 'variant = release cxxflags = -DBOOST_DISABLE_ASSERTS'. + </p> +<div class="table"> +<a name="context.econtext.performance.performance_of_context_switch"></a><p class="title"><b>Table 1.1. Performance of context switch</b></p> +<div class="table-contents"><table class="table" summary="Performance of context switch"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Platform + </p> + </th> +<th> + <p> + ucontext_t + </p> + </th> +<th> + <p> + fcontext_t + </p> + </th> +<th> + <p> + windows fibers + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + i386 <sup>[<a name="context.econtext.performance.f0" href="#ftn.context.econtext.performance.f0" class="footnote">a</a>]</sup> + </p> + </td> +<td> + <p> + 708 ns / 754 cycles + </p> + </td> +<td> + <p> + 37 ns / 37 cycles + </p> + </td> +<td> + <p> + ns / cycles + </p> + </td> +</tr> +<tr> +<td> + <p> + x86_64 <sup>[<a name="context.econtext.performance.f1" href="#ftn.context.econtext.performance.f1" class="footnote">b</a>]</sup> + </p> + </td> +<td> + <p> + 547 ns / 1433 cycles + </p> + </td> +<td> + <p> + 8 ns / 23 cycles + </p> + </td> +<td> + <p> + ns / cycles + </p> + </td> +</tr> +</tbody> +<tbody class="footnotes"><tr><td colspan="4"> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.performance.f0" href="#context.econtext.performance.f0" class="para">a</a>] </sup> + AMD Athlon 64 DualCore 4400+ + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.performance.f1" href="#context.econtext.performance.f1" class="para">b</a>] </sup> + Intel Core2 Q6700 + </p></div> +</td></tr></tbody> +</table></div> +</div> +<br class="table-break"> +</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 © 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="stack/stack_context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="architectures.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/rationale.html b/libs/context/doc/html/context/econtext/rationale.html new file mode 100644 index 000000000..a7674b4fd --- /dev/null +++ b/libs/context/doc/html/context/econtext/rationale.html @@ -0,0 +1,87 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Rationale</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="architectures.html" title="Architectures"> +<link rel="next" href="rationale/other_apis_.html" title="Other APIs"> +</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="architectures.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="rationale/other_apis_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a> +</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="rationale/other_apis_.html">Other APIs + </a></span></dt> +<dt><span class="section"><a href="rationale/x86_and_floating_point_env.html">x86 + and floating-point env</a></span></dt> +</dl></div> +<h5> +<a name="context.econtext.rationale.h0"></a> + <span><a name="context.econtext.rationale.no_inline_assembler"></a></span><a class="link" href="rationale.html#context.econtext.rationale.no_inline_assembler">No + inline-assembler</a> + </h5> +<p> + Some newer compiler (for instance MSVC 10 for x86_64 and itanium) do not + support inline assembler. <sup>[<a name="context.econtext.rationale.f0" href="#ftn.context.econtext.rationale.f0" class="footnote">1</a>]</sup>. Inlined assembler generates code bloating which his not welcome + on embedded systems. + </p> +<h5> +<a name="context.econtext.rationale.h1"></a> + <span><a name="context.econtext.rationale.fcontext_t"></a></span><a class="link" href="rationale.html#context.econtext.rationale.fcontext_t">fcontext_t</a> + </h5> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the low level API + fcontext_t which is implemented in assembler to provide context swapping + operations. fcontext_t is the part to port to new platforms. + </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> + Context switches do not preserve the signal mask on UNIX systems. + </p></td></tr> +</table></div> +<p> + <span class="emphasis"><em>fcontext_t</em></span> is an opaque pointer. + </p> +<div class="footnotes"> +<br><hr width="100" align="left"> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.f0" href="#context.econtext.rationale.f0" class="para">1</a>] </sup> + <a href="http://msdn.microsoft.com/en-us/library/4ks26t93.aspx" target="_top">MSDN + article 'Inline Assembler'</a> + </p></div> +</div> +</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 © 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="architectures.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="rationale/other_apis_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/rationale/other_apis_.html b/libs/context/doc/html/context/econtext/rationale/other_apis_.html new file mode 100644 index 000000000..194d3e88c --- /dev/null +++ b/libs/context/doc/html/context/econtext/rationale/other_apis_.html @@ -0,0 +1,119 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Other APIs</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 1. Context"> +<link rel="up" href="../rationale.html" title="Rationale"> +<link rel="prev" href="../rationale.html" title="Rationale"> +<link rel="next" href="x86_and_floating_point_env.html" title="x86 and floating-point env"> +</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="../rationale.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.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="x86_and_floating_point_env.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.rationale.other_apis_"></a><a class="link" href="other_apis_.html" title="Other APIs">Other APIs + </a> +</h4></div></div></div> +<h6> +<a name="context.econtext.rationale.other_apis_.h0"></a> + <span><a name="context.econtext.rationale.other_apis_.setjmp___longjmp__"></a></span><a class="link" href="other_apis_.html#context.econtext.rationale.other_apis_.setjmp___longjmp__">setjmp()/longjmp()</a> + </h6> +<p> + C99 defines <code class="computeroutput"><span class="identifier">setjmp</span><span class="special">()</span></code>/<code class="computeroutput"><span class="identifier">longjmp</span><span class="special">()</span></code> + to provide non-local jumps but it does not require that <span class="emphasis"><em>longjmp()</em></span> + preserves the current stack frame. Therefore, jumping into a function which + was exited via a call to <span class="emphasis"><em>longjmp()</em></span> is undefined <sup>[<a name="context.econtext.rationale.other_apis_.f0" href="#ftn.context.econtext.rationale.other_apis_.f0" class="footnote">2</a>]</sup>. + </p> +<h6> +<a name="context.econtext.rationale.other_apis_.h1"></a> + <span><a name="context.econtext.rationale.other_apis_.ucontext_t"></a></span><a class="link" href="other_apis_.html#context.econtext.rationale.other_apis_.ucontext_t">ucontext_t</a> + </h6> +<p> + Since POSIX.1-2003 <code class="computeroutput"><span class="identifier">ucontext_t</span></code> + is deprecated and was removed in POSIX.1-2008! The function signature of + <code class="computeroutput"><span class="identifier">makecontext</span><span class="special">()</span></code> + is: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">makecontext</span><span class="special">(</span><span class="identifier">ucontext_t</span> <span class="special">*</span><span class="identifier">ucp</span><span class="special">,</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">func</span><span class="special">)(),</span> <span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="special">...);</span> +</pre> +<p> + The third argument of <code class="computeroutput"><span class="identifier">makecontext</span><span class="special">()</span></code> specifies the number of integer arguments + that follow which will require function pointer cast if <code class="computeroutput"><span class="identifier">func</span></code> + will accept those arguments which is undefined in C99 <sup>[<a name="context.econtext.rationale.other_apis_.f1" href="#ftn.context.econtext.rationale.other_apis_.f1" class="footnote">3</a>]</sup>. + </p> +<p> + The arguments in the var-arg list are required to be integers, passing + pointers in var-arg list is not guaranteed to work, especially it will + fail for architectures where pointers are larger than integers. + </p> +<p> + <code class="computeroutput"><span class="identifier">ucontext_t</span></code> preserves signal + mask between context switches which involves system calls consuming a lot + of CPU cycles (ucontext_t is slower by perfomance_link[factor 13x] relative + to <code class="computeroutput"><span class="identifier">fcontext_t</span></code>). + </p> +<h6> +<a name="context.econtext.rationale.other_apis_.h2"></a> + <span><a name="context.econtext.rationale.other_apis_.windows_fibers"></a></span><a class="link" href="other_apis_.html#context.econtext.rationale.other_apis_.windows_fibers">Windows + fibers</a> + </h6> +<p> + A drawback of Windows Fiber API is that <code class="computeroutput"><span class="identifier">CreateFiber</span><span class="special">()</span></code> does not accept a pointer to user allocated + stack space preventing the reuse of stacks for other context instances. + Because the Windows Fiber API requires to call <code class="computeroutput"><span class="identifier">ConvertThreadToFiber</span><span class="special">()</span></code> if <code class="computeroutput"><span class="identifier">SwitchFiber</span><span class="special">()</span></code> is called for a thread which has not + been converted to a fiber. For the same reason <code class="computeroutput"><span class="identifier">ConvertFiberToThread</span><span class="special">()</span></code> must be called after return from <code class="computeroutput"><span class="identifier">SwitchFiber</span><span class="special">()</span></code> + if the thread was forced to be converted to a fiber before (which is inefficient). + </p> +<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span> <span class="special">!</span> <span class="identifier">is_a_fiber</span><span class="special">()</span> <span class="special">)</span> +<span class="special">{</span> + <span class="identifier">ConvertThreadToFiber</span><span class="special">(</span> <span class="number">0</span><span class="special">);</span> + <span class="identifier">SwitchToFiber</span><span class="special">(</span> <span class="identifier">ctx</span><span class="special">);</span> + <span class="identifier">ConvertFiberToThread</span><span class="special">();</span> +<span class="special">}</span> +</pre> +<p> + If the condition <code class="computeroutput"><span class="identifier">_WIN32_WINNT</span> + <span class="special">>=</span> <span class="identifier">_WIN32_WINNT_VISTA</span></code> + is met function <code class="computeroutput"><span class="identifier">IsThreadAFiber</span><span class="special">()</span></code> is provided in order to detect if the + current thread was already converted. Unfortunately Windows XP + SP 2/3 + defines <code class="computeroutput"><span class="identifier">_WIN32_WINNT</span> <span class="special">>=</span> + <span class="identifier">_WIN32_WINNT_VISTA</span></code> without providing + <code class="computeroutput"><span class="identifier">IsThreadAFiber</span><span class="special">()</span></code>. + </p> +<div class="footnotes"> +<br><hr width="100" align="left"> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.other_apis_.f0" href="#context.econtext.rationale.other_apis_.f0" class="para">2</a>] </sup> + ISO/IEC 9899:1999, 2005, 7.13.2.1:2 + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.other_apis_.f1" href="#context.econtext.rationale.other_apis_.f1" class="para">3</a>] </sup> + ISO/IEC 9899:1999, 2005, J.2 + </p></div> +</div> +</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 © 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="../rationale.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.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="x86_and_floating_point_env.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/rationale/x86_and_floating_point_env.html b/libs/context/doc/html/context/econtext/rationale/x86_and_floating_point_env.html new file mode 100644 index 000000000..201b6e43c --- /dev/null +++ b/libs/context/doc/html/context/econtext/rationale/x86_and_floating_point_env.html @@ -0,0 +1,124 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>x86 and floating-point env</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 1. Context"> +<link rel="up" href="../rationale.html" title="Rationale"> +<link rel="prev" href="other_apis_.html" title="Other APIs"> +<link rel="next" href="../reference.html" title="Reference"> +</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="other_apis_.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.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="../reference.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.rationale.x86_and_floating_point_env"></a><a class="link" href="x86_and_floating_point_env.html" title="x86 and floating-point env">x86 + and floating-point env</a> +</h4></div></div></div> +<h6> +<a name="context.econtext.rationale.x86_and_floating_point_env.h0"></a> + <span><a name="context.econtext.rationale.x86_and_floating_point_env.i386"></a></span><a class="link" href="x86_and_floating_point_env.html#context.econtext.rationale.x86_and_floating_point_env.i386">i386</a> + </h6> +<p> + "The FpCsr and the MxCsr register must be saved and restored before + any call or return by any procedure that needs to modify them ..." + <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f0" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f0" class="footnote">4</a>]</sup>. + </p> +<h6> +<a name="context.econtext.rationale.x86_and_floating_point_env.h1"></a> + <span><a name="context.econtext.rationale.x86_and_floating_point_env.x86_64"></a></span><a class="link" href="x86_and_floating_point_env.html#context.econtext.rationale.x86_and_floating_point_env.x86_64">x86_64</a> + </h6> +<h6> +<a name="context.econtext.rationale.x86_and_floating_point_env.h2"></a> + <span><a name="context.econtext.rationale.x86_and_floating_point_env.windows"></a></span><a class="link" href="x86_and_floating_point_env.html#context.econtext.rationale.x86_and_floating_point_env.windows">Windows</a> + </h6> +<p> + MxCsr - "A callee that modifies any of the non-volatile fields within + MxCsr must restore them before returning to its caller. Furthermore, a + caller that has modified any of these fields must restore them to their + standard values before invoking a callee ..." <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f1" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f1" class="footnote">5</a>]</sup>. + </p> +<p> + FpCsr - "A callee that modifies any of the fields within FpCsr must + restore them before returning to its caller. Furthermore, a caller that + has modified any of these fields must restore them to their standard values + before invoking a callee ..." <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f2" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f2" class="footnote">6</a>]</sup>. + </p> +<p> + "The MMX and floating-point stack registers (MM0-MM7/ST0-ST7) are + preserved across context switches. There is no explicit calling convention + for these registers." <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f3" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f3" class="footnote">7</a>]</sup>. + </p> +<p> + "The 64-bit Microsoft compiler does not use ST(0)-ST(7)/MM0-MM7". + <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f4" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f4" class="footnote">8</a>]</sup>. + </p> +<p> + "XMM6-XMM15 must be preserved" <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f5" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f5" class="footnote">9</a>]</sup> + </p> +<h6> +<a name="context.econtext.rationale.x86_and_floating_point_env.h3"></a> + <span><a name="context.econtext.rationale.x86_and_floating_point_env.sysv"></a></span><a class="link" href="x86_and_floating_point_env.html#context.econtext.rationale.x86_and_floating_point_env.sysv">SysV</a> + </h6> +<p> + "The control bits of the MxCsr register are callee-saved (preserved + across calls), while the status bits are caller-saved (not preserved). + The x87 status word register is caller-saved, whereas the x87 control word + (FpCsr) is callee-saved." <sup>[<a name="context.econtext.rationale.x86_and_floating_point_env.f6" href="#ftn.context.econtext.rationale.x86_and_floating_point_env.f6" class="footnote">10</a>]</sup>. + </p> +<div class="footnotes"> +<br><hr width="100" align="left"> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f0" href="#context.econtext.rationale.x86_and_floating_point_env.f0" class="para">4</a>] </sup> + 'Calling Conventions', Agner Fog + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f1" href="#context.econtext.rationale.x86_and_floating_point_env.f1" class="para">5</a>] </sup> + <a href="http://http://msdn.microsoft.com/en-us/library/yxty7t75.aspx" target="_top">MSDN + article 'MxCsr'</a> + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f2" href="#context.econtext.rationale.x86_and_floating_point_env.f2" class="para">6</a>] </sup> + <a href="http://http://msdn.microsoft.com/en-us/library/ms235300.aspx" target="_top">MSDN + article 'FpCsr'</a> + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f3" href="#context.econtext.rationale.x86_and_floating_point_env.f3" class="para">7</a>] </sup> + <a href="http://msdn.microsoft.com/en-us/library/a32tsf7t%28VS.80%29.aspx" target="_top">MSDN + article 'Legacy Floating-Point Support'</a> + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f4" href="#context.econtext.rationale.x86_and_floating_point_env.f4" class="para">8</a>] </sup> + 'Calling Conventions', Agner Fog + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f5" href="#context.econtext.rationale.x86_and_floating_point_env.f5" class="para">9</a>] </sup> + <a href="http://msdn.microsoft.com/en-us/library/9z1stfyw%28v=vs.100%29.aspx" target="_top">MSDN + article 'Register Usage'</a> + </p></div> +<div class="footnote"><p><sup>[<a name="ftn.context.econtext.rationale.x86_and_floating_point_env.f6" href="#context.econtext.rationale.x86_and_floating_point_env.f6" class="para">10</a>] </sup> + SysV ABI AMD64 Architecture Processor Supplement Draft Version 0.99.4, + 3.2.1 + </p></div> +</div> +</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 © 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="other_apis_.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.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="../reference.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/reference.html b/libs/context/doc/html/context/econtext/reference.html new file mode 100644 index 000000000..509e43b8e --- /dev/null +++ b/libs/context/doc/html/context/econtext/reference.html @@ -0,0 +1,104 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Reference</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="rationale/x86_and_floating_point_env.html" title="x86 and floating-point env"> +<link rel="next" href="acknowledgements.html" title="Acknowledgments"> +</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="rationale/x86_and_floating_point_env.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="acknowledgements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a> +</h3></div></div></div> +<h5> +<a name="context.econtext.reference.h0"></a> + <span><a name="context.econtext.reference.arm"></a></span><a class="link" href="reference.html#context.econtext.reference.arm">ARM</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + AAPCS ABI: Procedure Call Standard for the ARM Architecture + </li> +<li class="listitem"> + AAPCS/LINUX: ARM GNU/Linux Application Binary Interface Supplement + </li> +</ul></div> +<h5> +<a name="context.econtext.reference.h1"></a> + <span><a name="context.econtext.reference.mips"></a></span><a class="link" href="reference.html#context.econtext.reference.mips">MIPS</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + O32 ABI: SYSTEM V APPLICATION BINARY INTERFACE, MIPS RISC Processor Supplement + </li></ul></div> +<h5> +<a name="context.econtext.reference.h2"></a> + <span><a name="context.econtext.reference.powerpc32"></a></span><a class="link" href="reference.html#context.econtext.reference.powerpc32">PowerPC32</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE PowerPC Processor Supplement + </li></ul></div> +<h5> +<a name="context.econtext.reference.h3"></a> + <span><a name="context.econtext.reference.powerpc64"></a></span><a class="link" href="reference.html#context.econtext.reference.powerpc64">PowerPC64</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + SYSV ABI: PowerPC User Instruction Set Architecture, Book I + </li></ul></div> +<h5> +<a name="context.econtext.reference.h4"></a> + <span><a name="context.econtext.reference.x86_32"></a></span><a class="link" href="reference.html#context.econtext.reference.x86_32">X86-32</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE, Intel386TM Architecture + Processor Supplement + </li> +<li class="listitem"> + MS PE: <a href="http://msdn.microsoft.com/en-us/library/k2b2ssfy.aspx" target="_top">Calling + Conventions</a> + </li> +</ul></div> +<h5> +<a name="context.econtext.reference.h5"></a> + <span><a name="context.econtext.reference.x86_64"></a></span><a class="link" href="reference.html#context.econtext.reference.x86_64">X86-64</a> + </h5> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + SYSV ABI: System V Application Binary Interface, AMD64 Architecture Processor + Supplement + </li> +<li class="listitem"> + MS PE: <a href="http://msdn.microsoft.com/en-us/library/7kcdt6fy%28VS.80%29.aspx" target="_top">x64 + Software Conventions</a> + </li> +</ul></div> +</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 © 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="rationale/x86_and_floating_point_env.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="acknowledgements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack.html b/libs/context/doc/html/context/econtext/stack.html new file mode 100644 index 000000000..e871d7d0d --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack.html @@ -0,0 +1,184 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Stack allocation</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 1. Context"> +<link rel="up" href="../econtext.html" title="Execution context"> +<link rel="prev" href="../econtext.html" title="Execution context"> +<link rel="next" href="stack/protected_fixedsize.html" title="Class protected_fixedsize"> +</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="../econtext.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="stack/protected_fixedsize.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.econtext.stack"></a><a class="link" href="stack.html" title="Stack allocation">Stack allocation</a> +</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="stack/protected_fixedsize.html">Class + <span class="emphasis"><em>protected_fixedsize</em></span></a></span></dt> +<dt><span class="section"><a href="stack/fixedsize.html">Class <span class="emphasis"><em>fixedsize</em></span></a></span></dt> +<dt><span class="section"><a href="stack/segmented.html">Class <span class="emphasis"><em>segmented</em></span></a></span></dt> +<dt><span class="section"><a href="stack/stack_traits.html">Class <span class="emphasis"><em>stack_traits</em></span></a></span></dt> +<dt><span class="section"><a href="stack/stack_context.html">Class <span class="emphasis"><em>stack_context</em></span></a></span></dt> +</dl></div> +<p> + The memory used by the stack is allocated/deallocated via a <span class="emphasis"><em>StackAllocator</em></span> + which is required to model a <span class="emphasis"><em>stack-allocator concept</em></span>. + </p> +<h5> +<a name="context.econtext.stack.h0"></a> + <span><a name="context.econtext.stack._emphasis_stack_allocator_concept__emphasis_"></a></span><a class="link" href="stack.html#context.econtext.stack._emphasis_stack_allocator_concept__emphasis_"><span class="emphasis"><em>stack-allocator + concept</em></span></a> + </h5> +<p> + A <span class="emphasis"><em>StackAllocator</em></span> must satisfy the <span class="emphasis"><em>stack-allocator + concept</em></span> requirements shown in the following table, in which <code class="computeroutput"><span class="identifier">a</span></code> is an object of a <span class="emphasis"><em>StackAllocator</em></span> + type, <code class="computeroutput"><span class="identifier">sctx</span></code> is a <code class="computeroutput"><span class="identifier">stack_context</span></code>, and <code class="computeroutput"><span class="identifier">size</span></code> + is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>: + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + expression + </p> + </th> +<th> + <p> + return type + </p> + </th> +<th> + <p> + notes + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">(</span><span class="identifier">size</span><span class="special">)</span></code> + </p> + </td> +<td> + </td> +<td> + <p> + creates a stack allocator + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">stack_context</span></code> + </p> + </td> +<td> + <p> + creates a stack + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span> + <span class="identifier">sctx</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">void</span></code> + </p> + </td> +<td> + <p> + deallocates the stack created by <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +<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> + The implementation of <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> might include logic to protect against + exceeding the context's available stack size rather than leaving it as + undefined behaviour. + </p></td></tr> +</table></div> +<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> + Calling <code class="computeroutput"><span class="identifier">deallocate</span><span class="special">()</span></code> + with a <code class="computeroutput"><span class="identifier">stack_context</span></code> not + set by <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> + results in undefined behaviour. + </p></td></tr> +</table></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> + The stack is not required to be aligned; alignment takes place inside + <span class="emphasis"><em>execution_context</em></span>. + </p></td></tr> +</table></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> + Depending on the architecture <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> stores an address from the top of the + stack (growing downwards) or the bottom of the stack (growing upwards). + </p></td></tr> +</table></div> +</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 © 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="../econtext.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../econtext.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="stack/protected_fixedsize.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack/fixedsize.html b/libs/context/doc/html/context/econtext/stack/fixedsize.html new file mode 100644 index 000000000..80bce593a --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack/fixedsize.html @@ -0,0 +1,113 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class fixedsize</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 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="protected_fixedsize.html" title="Class protected_fixedsize"> +<link rel="next" href="segmented.html" title="Class segmented"> +</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="protected_fixedsize.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="segmented.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.stack.fixedsize"></a><a class="link" href="fixedsize.html" title="Class fixedsize">Class <span class="emphasis"><em>fixedsize</em></span></a> +</h4></div></div></div> +<p> + __boost_coroutine__ provides the class <span class="emphasis"><em>fixedsize</em></span> which + models the <span class="emphasis"><em>stack-allocator concept</em></span>. In contrast to + <span class="emphasis"><em>protected_fixedsize</em></span> it does not append a guard page + at the end of each stack. The memory is simply managed by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">free</span><span class="special">()</span></code>. + </p> +<pre class="programlisting"><span class="preprocessor">#include</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">fixedsize</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_fixedsize</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_fixesize</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_fixedsize</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">fixedsize</span> +</pre> +<h6> +<a name="context.econtext.stack.fixedsize.h0"></a> + <span><a name="context.econtext.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="fixedsize.html#context.econtext.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> + <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.fixedsize.h1"></a> + <span><a name="context.econtext.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="fixedsize.html#context.econtext.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> + <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="protected_fixedsize.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="segmented.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack/protected_fixedsize.html b/libs/context/doc/html/context/econtext/stack/protected_fixedsize.html new file mode 100644 index 000000000..80c5407b9 --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack/protected_fixedsize.html @@ -0,0 +1,136 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class protected_fixedsize</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 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="../stack.html" title="Stack allocation"> +<link rel="next" href="fixedsize.html" title="Class fixedsize"> +</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="../stack.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="fixedsize.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.stack.protected_fixedsize"></a><a class="link" href="protected_fixedsize.html" title="Class protected_fixedsize">Class + <span class="emphasis"><em>protected_fixedsize</em></span></a> +</h4></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the class <span class="emphasis"><em>protected_fixedsize</em></span> + which models the <span class="emphasis"><em>stack-allocator concept</em></span>. It appends + a guard page at the end of each stack to protect against exceeding the + stack. If the guard page is accessed (read or write operation) a segmentation + fault/access violation is generated by the operating system. + </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> + Using <span class="emphasis"><em>protected_fixedsize</em></span> is expensive. That is, + launching a new coroutine with a new stack is expensive; the allocated + stack is just as efficient to use as any other stack. + </p></td></tr> +</table></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> + The appended <code class="computeroutput"><span class="identifier">guard</span> <span class="identifier">page</span></code> + is <span class="bold"><strong>not</strong></span> mapped to physical memory, only + virtual addresses are used. + </p></td></tr> +</table></div> +<pre class="programlisting"><span class="preprocessor">#include</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">protected_fixedsize</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_protected_fixedsize</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_protected_fixesize</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_protected_fixedsize</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">protected_fixedsize</span> +</pre> +<h6> +<a name="context.econtext.stack.protected_fixedsize.h0"></a> + <span><a name="context.econtext.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="protected_fixedsize.html#context.econtext.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> + <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.protected_fixedsize.h1"></a> + <span><a name="context.econtext.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="protected_fixedsize.html#context.econtext.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> + <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="../stack.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="fixedsize.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack/segmented.html b/libs/context/doc/html/context/econtext/stack/segmented.html new file mode 100644 index 000000000..4339720ee --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack/segmented.html @@ -0,0 +1,129 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class segmented</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 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="fixedsize.html" title="Class fixedsize"> +<link rel="next" href="stack_traits.html" title="Class stack_traits"> +</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="fixedsize.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_traits.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.stack.segmented"></a><a class="link" href="segmented.html" title="Class segmented">Class <span class="emphasis"><em>segmented</em></span></a> +</h4></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> supports usage of a <span class="emphasis"><em>segmented</em></span>, + e. g. the size of the stack grows on demand. The coroutine is created with + a minimal stack size and will be increased as required. Class <span class="emphasis"><em>segmented</em></span> + models the <span class="emphasis"><em>stack-allocator concept</em></span>. In contrast to + <span class="emphasis"><em>protected_fixedsize</em></span> and <span class="emphasis"><em>fixedsize</em></span> + it creates a stack which grows on demand. + </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> + Segmented stacks are currently only supported by <span class="bold"><strong>gcc</strong></span> + from version <span class="bold"><strong>4.7</strong></span> <span class="bold"><strong>clang</strong></span> + from version <span class="bold"><strong>3.4</strong></span> onwards. In order to + use a __segmented_stack__ <span class="bold"><strong>Boost.Context</strong></span> + must be built with <span class="bold"><strong>toolset=gcc segmented-stacks=on</strong></span> + at b2/bjam command-line. Applications must be compiled with compiler-flags + <span class="bold"><strong>-fsplit-stack -DBOOST_USE_SEGMENTED_STACKS</strong></span>. + </p></td></tr> +</table></div> +<pre class="programlisting"><span class="preprocessor">#include</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">segmented</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_segmented</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_segmented</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_segmented</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">segmented</span><span class="special">;</span> +</pre> +<h6> +<a name="context.econtext.stack.segmented.h0"></a> + <span><a name="context.econtext.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="segmented.html#context.econtext.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> + <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.segmented.h1"></a> + <span><a name="context.econtext.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="segmented.html#context.econtext.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> + <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="fixedsize.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_traits.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack/stack_context.html b/libs/context/doc/html/context/econtext/stack/stack_context.html new file mode 100644 index 000000000..ea84c026d --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack/stack_context.html @@ -0,0 +1,84 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class stack_context</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 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="stack_traits.html" title="Class stack_traits"> +<link rel="next" href="../../performance.html" title="Performance"> +</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="stack_traits.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="../../performance.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.stack.stack_context"></a><a class="link" href="stack_context.html" title="Class stack_context">Class <span class="emphasis"><em>stack_context</em></span></a> +</h4></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the class <span class="emphasis"><em>stack_context</em></span> + which will contain the stack pointer and the size of the stack. In case + of a <span class="emphasis"><em>segmented</em></span>, <span class="emphasis"><em>stack_context</em></span> + contains some extra control structures. + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">stack_context</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="comment">// might contain additional control structures</span> + <span class="comment">// for instance for segmented stacks</span> +<span class="special">}</span> +</pre> +<h6> +<a name="context.econtext.stack.stack_context.h0"></a> + <span><a name="context.econtext.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="stack_context.html#context.econtext.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">sp</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Value:</span></dt> +<dd><p> + Pointer to the beginning of the stack. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.stack_context.h1"></a> + <span><a name="context.econtext.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="stack_context.html#context.econtext.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Value:</span></dt> +<dd><p> + Actual size of the stack. + </p></dd> +</dl> +</div> +</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 © 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="stack_traits.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="../../performance.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/econtext/stack/stack_traits.html b/libs/context/doc/html/context/econtext/stack/stack_traits.html new file mode 100644 index 000000000..88e48009b --- /dev/null +++ b/libs/context/doc/html/context/econtext/stack/stack_traits.html @@ -0,0 +1,158 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class stack_traits</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 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="segmented.html" title="Class segmented"> +<link rel="next" href="stack_context.html" title="Class stack_context"> +</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="segmented.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_context.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="context.econtext.stack.stack_traits"></a><a class="link" href="stack_traits.html" title="Class stack_traits">Class <span class="emphasis"><em>stack_traits</em></span></a> +</h4></div></div></div> +<p> + <span class="emphasis"><em>stack_traits</em></span> models a <span class="emphasis"><em>stack-traits</em></span> + providing a way to access certain properites defined by the enironment. + Stack allocators use <span class="emphasis"><em>stack-traits</em></span> to allocate stacks. + </p> +<pre class="programlisting"><span class="preprocessor">#include</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">stack_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">stack_traits</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">is_unbounded</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">page_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">default_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">minimum_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">maximum_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<h6> +<a name="context.econtext.stack.stack_traits.h0"></a> + <span><a name="context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">is_unbounded</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns <code class="computeroutput"><span class="keyword">true</span></code> if the + environment defines no limit for the size of a stack. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.stack_traits.h1"></a> + <span><a name="context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">page_size</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the page size in bytes. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.stack_traits.h2"></a> + <span><a name="context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">default_size</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns a default stack size, which may be platform specific. If + the stack is unbounded then the present implementation returns the + maximum of <code class="computeroutput"><span class="number">64</span> <span class="identifier">kB</span></code> + and <code class="computeroutput"><span class="identifier">minimum_size</span><span class="special">()</span></code>. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.stack_traits.h3"></a> + <span><a name="context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">minimum_size</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the minimum size in bytes of stack defined by the environment + (Win32 4kB/Win64 8kB, defined by rlimit on POSIX). + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h6> +<a name="context.econtext.stack.stack_traits.h4"></a> + <span><a name="context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.econtext.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">maximum_size</span><span class="special">()</span></code></a> + </h6> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">is_unbounded</span><span class="special">()</span></code> + returns <code class="computeroutput"><span class="keyword">false</span></code>. + </p></dd> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the maximum size in bytes of stack defined by the environment. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +</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 © 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="segmented.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_context.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/overview.html b/libs/context/doc/html/context/overview.html index 7080161b6..e67770020 100644 --- a/libs/context/doc/html/context/overview.html +++ b/libs/context/doc/html/context/overview.html @@ -69,7 +69,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/performance.html b/libs/context/doc/html/context/performance.html index 00227d0d3..c6aede3d4 100644 --- a/libs/context/doc/html/context/performance.html +++ b/libs/context/doc/html/context/performance.html @@ -6,7 +6,7 @@ <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="Chapter 1. Context"> <link rel="up" href="../index.html" title="Chapter 1. Context"> -<link rel="prev" href="context/boost_fcontext.html" title="fcontext_t and related functions"> +<link rel="prev" href="stack/valgrind.html" title="Support for valgrind"> <link rel="next" href="architectures.html" title="Architectures"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> @@ -20,7 +20,7 @@ </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="context/boost_fcontext.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="architectures.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="stack/valgrind.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="architectures.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"> @@ -125,7 +125,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> @@ -133,7 +133,7 @@ </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="context/boost_fcontext.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="architectures.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="stack/valgrind.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="architectures.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/context/doc/html/context/rationale.html b/libs/context/doc/html/context/rationale.html index 8c8b6338d..23144d7d7 100644 --- a/libs/context/doc/html/context/rationale.html +++ b/libs/context/doc/html/context/rationale.html @@ -72,7 +72,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/rationale/other_apis_.html b/libs/context/doc/html/context/rationale/other_apis_.html index e9c066c6f..276468ad0 100644 --- a/libs/context/doc/html/context/rationale/other_apis_.html +++ b/libs/context/doc/html/context/rationale/other_apis_.html @@ -103,7 +103,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/rationale/x86_and_floating_point_env.html b/libs/context/doc/html/context/rationale/x86_and_floating_point_env.html index c2b9fe3c5..49c2d0f2f 100644 --- a/libs/context/doc/html/context/rationale/x86_and_floating_point_env.html +++ b/libs/context/doc/html/context/rationale/x86_and_floating_point_env.html @@ -110,7 +110,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/reference.html b/libs/context/doc/html/context/reference.html index b2877c2db..a4a18b319 100644 --- a/libs/context/doc/html/context/reference.html +++ b/libs/context/doc/html/context/reference.html @@ -90,7 +90,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/requirements.html b/libs/context/doc/html/context/requirements.html index 27ccae0f3..beb8704da 100644 --- a/libs/context/doc/html/context/requirements.html +++ b/libs/context/doc/html/context/requirements.html @@ -7,7 +7,7 @@ <link rel="home" href="../index.html" title="Chapter 1. Context"> <link rel="up" href="../index.html" title="Chapter 1. Context"> <link rel="prev" href="overview.html" title="Overview"> -<link rel="next" href="context.html" title="Context"> +<link rel="next" href="context.html" title="Struct fcontext_t"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> @@ -67,7 +67,7 @@ </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 © 2009 Oliver Kowalke<p> +<td align="right"><div class="copyright-footer">Copyright © 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> diff --git a/libs/context/doc/html/context/stack.html b/libs/context/doc/html/context/stack.html new file mode 100644 index 000000000..699c984c3 --- /dev/null +++ b/libs/context/doc/html/context/stack.html @@ -0,0 +1,183 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Stack allocation</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Chapter 1. Context"> +<link rel="up" href="../index.html" title="Chapter 1. Context"> +<link rel="prev" href="econtext.html" title="Class execution_context"> +<link rel="next" href="stack/protected_fixedsize.html" title="Class protected_fixedsize"> +</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="econtext.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="stack/protected_fixedsize.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.stack"></a><a class="link" href="stack.html" title="Stack allocation">Stack allocation</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="stack/protected_fixedsize.html">Class <span class="emphasis"><em>protected_fixedsize</em></span></a></span></dt> +<dt><span class="section"><a href="stack/fixedsize.html">Class <span class="emphasis"><em>fixedsize_stack</em></span></a></span></dt> +<dt><span class="section"><a href="stack/segmented.html">Class <span class="emphasis"><em>segmented_stack</em></span></a></span></dt> +<dt><span class="section"><a href="stack/stack_traits.html">Class <span class="emphasis"><em>stack_traits</em></span></a></span></dt> +<dt><span class="section"><a href="stack/stack_context.html">Class <span class="emphasis"><em>stack_context</em></span></a></span></dt> +<dt><span class="section"><a href="stack/valgrind.html">Support for valgrind</a></span></dt> +</dl></div> +<p> + The memory used by the stack is allocated/deallocated via a <span class="emphasis"><em>StackAllocator</em></span> + which is required to model a <span class="emphasis"><em>stack-allocator concept</em></span>. + </p> +<h4> +<a name="context.stack.h0"></a> + <span class="phrase"><a name="context.stack._emphasis_stack_allocator_concept__emphasis_"></a></span><a class="link" href="stack.html#context.stack._emphasis_stack_allocator_concept__emphasis_"><span class="emphasis"><em>stack-allocator + concept</em></span></a> + </h4> +<p> + A <span class="emphasis"><em>StackAllocator</em></span> must satisfy the <span class="emphasis"><em>stack-allocator + concept</em></span> requirements shown in the following table, in which <code class="computeroutput"><span class="identifier">a</span></code> is an object of a <span class="emphasis"><em>StackAllocator</em></span> + type, <code class="computeroutput"><span class="identifier">sctx</span></code> is a <code class="computeroutput"><span class="identifier">stack_context</span></code>, and <code class="computeroutput"><span class="identifier">size</span></code> + is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>: + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + expression + </p> + </th> +<th> + <p> + return type + </p> + </th> +<th> + <p> + notes + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">(</span><span class="identifier">size</span><span class="special">)</span></code> + </p> + </td> +<td> + </td> +<td> + <p> + creates a stack allocator + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">stack_context</span></code> + </p> + </td> +<td> + <p> + creates a stack + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span> + <span class="identifier">sctx</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">void</span></code> + </p> + </td> +<td> + <p> + deallocates the stack created by <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +<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> + The implementation of <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> might include logic to protect against + exceeding the context's available stack size rather than leaving it as undefined + behaviour. + </p></td></tr> +</table></div> +<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> + Calling <code class="computeroutput"><span class="identifier">deallocate</span><span class="special">()</span></code> + with a <code class="computeroutput"><span class="identifier">stack_context</span></code> not + set by <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> + results in undefined behaviour. + </p></td></tr> +</table></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> + The stack is not required to be aligned; alignment takes place inside <span class="emphasis"><em>execution_context</em></span>. + </p></td></tr> +</table></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> + Depending on the architecture <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> stores an address from the top of the stack + (growing downwards) or the bottom of the stack (growing upwards). + </p></td></tr> +</table></div> +</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 © 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="econtext.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="stack/protected_fixedsize.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/fixedsize.html b/libs/context/doc/html/context/stack/fixedsize.html new file mode 100644 index 000000000..f430c200a --- /dev/null +++ b/libs/context/doc/html/context/stack/fixedsize.html @@ -0,0 +1,110 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class fixedsize_stack</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="protected_fixedsize.html" title="Class protected_fixedsize"> +<link rel="next" href="segmented.html" title="Class segmented_stack"> +</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="protected_fixedsize.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="segmented.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.fixedsize"></a><a class="link" href="fixedsize.html" title="Class fixedsize_stack">Class <span class="emphasis"><em>fixedsize_stack</em></span></a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the class <span class="emphasis"><em>fixedsize_stack</em></span> + which models the <span class="emphasis"><em>stack-allocator concept</em></span>. In contrast + to <span class="emphasis"><em>protected_fixedsize_stack</em></span> it does not append a guard + page at the end of each stack. The memory is simply managed by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">free</span><span class="special">()</span></code>. + </p> +<pre class="programlisting"><span class="preprocessor">#include</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">fixedsize_stack</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_fixedsize_stack</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_fixesize_stack</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_fixedsize_stack</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">fixedsize_stack</span><span class="special">;</span> +</pre> +<h5> +<a name="context.stack.fixedsize.h0"></a> + <span class="phrase"><a name="context.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="fixedsize.html#context.stack.fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.fixedsize.h1"></a> + <span class="phrase"><a name="context.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="fixedsize.html#context.stack.fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="protected_fixedsize.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="segmented.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/protected_fixedsize.html b/libs/context/doc/html/context/stack/protected_fixedsize.html new file mode 100644 index 000000000..99da13e1f --- /dev/null +++ b/libs/context/doc/html/context/stack/protected_fixedsize.html @@ -0,0 +1,133 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class protected_fixedsize</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="../stack.html" title="Stack allocation"> +<link rel="next" href="fixedsize.html" title="Class fixedsize_stack"> +</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="../stack.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="fixedsize.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.protected_fixedsize"></a><a class="link" href="protected_fixedsize.html" title="Class protected_fixedsize">Class <span class="emphasis"><em>protected_fixedsize</em></span></a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the class <span class="emphasis"><em>protected_fixedsize_stack</em></span> + which models the <span class="emphasis"><em>stack-allocator concept</em></span>. It appends + a guard page at the end of each stack to protect against exceeding the stack. + If the guard page is accessed (read or write operation) a segmentation fault/access + violation is generated by the operating system. + </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> + Using <span class="emphasis"><em>protected_fixedsize_stack</em></span> is expensive. That + is, launching a new coroutine with a new stack is expensive; the allocated + stack is just as efficient to use as any other stack. + </p></td></tr> +</table></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> + The appended <code class="computeroutput"><span class="identifier">guard</span> <span class="identifier">page</span></code> + is <span class="bold"><strong>not</strong></span> mapped to physical memory, only + virtual addresses are used. + </p></td></tr> +</table></div> +<pre class="programlisting"><span class="preprocessor">#include</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">protected_fixedsize</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_protected_fixedsize</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_protected_fixesize</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_protected_fixedsize</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">protected_fixedsize</span> +</pre> +<h5> +<a name="context.stack.protected_fixedsize.h0"></a> + <span class="phrase"><a name="context.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="protected_fixedsize.html#context.stack.protected_fixedsize._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.protected_fixedsize.h1"></a> + <span class="phrase"><a name="context.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="protected_fixedsize.html#context.stack.protected_fixedsize._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="../stack.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="fixedsize.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/segmented.html b/libs/context/doc/html/context/stack/segmented.html new file mode 100644 index 000000000..71b973900 --- /dev/null +++ b/libs/context/doc/html/context/stack/segmented.html @@ -0,0 +1,127 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class segmented_stack</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="fixedsize.html" title="Class fixedsize_stack"> +<link rel="next" href="stack_traits.html" title="Class stack_traits"> +</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="fixedsize.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.segmented"></a><a class="link" href="segmented.html" title="Class segmented_stack">Class <span class="emphasis"><em>segmented_stack</em></span></a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> supports usage of a <span class="emphasis"><em>segmented_stack</em></span>, + e. g. the size of the stack grows on demand. The coroutine is created with + a minimal stack size and will be increased as required. Class <span class="emphasis"><em>segmented_stack</em></span> + models the <span class="emphasis"><em>stack-allocator concept</em></span>. In contrast to + <span class="emphasis"><em>protected_fixedsize_stack</em></span> and <span class="emphasis"><em>fixedsize_stack</em></span> + it creates a stack which grows on demand. + </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> + Segmented stacks are currently only supported by <span class="bold"><strong>gcc</strong></span> + from version <span class="bold"><strong>4.7</strong></span> <span class="bold"><strong>clang</strong></span> + from version <span class="bold"><strong>3.4</strong></span> onwards. In order to + use a __segmented_stack__ <span class="bold"><strong>Boost.Context</strong></span> + must be built with <span class="bold"><strong>toolset=gcc segmented-stacks=on</strong></span> + at b2/bjam command-line. Applications must be compiled with compiler-flags + <span class="bold"><strong>-fsplit-stack -DBOOST_USE_SEGMENTED_STACKS</strong></span>. + </p></td></tr> +</table></div> +<pre class="programlisting"><span class="preprocessor">#include</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">segmented_stack</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">traitsT</span> <span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">basic_segmented_stack</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">traitT</span> <span class="identifier">traits_type</span><span class="special">;</span> + + <span class="identifier">basic_segmented_stack</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">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> + + <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> + + <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> +<span class="special">}</span> + +<span class="keyword">typedef</span> <span class="identifier">basic_segmented_stack</span><span class="special"><</span> <span class="identifier">stack_traits</span> <span class="special">></span> <span class="identifier">segmented_stack</span><span class="special">;</span> +</pre> +<h5> +<a name="context.stack.segmented.h0"></a> + <span class="phrase"><a name="context.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="segmented.html#context.stack.segmented._code__phrase_role__identifier__stack_context__phrase___phrase_role__identifier__allocate__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special"><=</span> <span class="identifier">size</span></code> + and <code class="computeroutput"><span class="special">!</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">&&</span> + <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> + Bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture + (the stack grows downwards/upwards) the stored address is the highest/lowest + address of the stack. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.segmented.h1"></a> + <span class="phrase"><a name="context.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="segmented.html#context.stack.segmented._code__phrase_role__keyword__void__phrase___phrase_role__identifier__deallocate__phrase__phrase_role__special_____phrase___phrase_role__identifier__stack_context__phrase___phrase_role__special___amp___phrase___phrase_role__identifier__sctx__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> + <span class="special">&</span> <span class="identifier">sctx</span><span class="special">)</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="special">!</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> + <span class="special">&&</span> <span class="special">(</span> + <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum</span><span class="special">:</span><span class="identifier">size</span><span class="special">()</span> + <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. + </p></dd> +<dt><span class="term">Effects:</span></dt> +<dd><p> + Deallocates the stack space. + </p></dd> +</dl> +</div> +</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 © 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="fixedsize.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/stack_context.html b/libs/context/doc/html/context/stack/stack_context.html new file mode 100644 index 000000000..9a4ad3861 --- /dev/null +++ b/libs/context/doc/html/context/stack/stack_context.html @@ -0,0 +1,85 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class stack_context</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="stack_traits.html" title="Class stack_traits"> +<link rel="next" href="valgrind.html" title="Support for valgrind"> +</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="stack_traits.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="valgrind.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.stack_context"></a><a class="link" href="stack_context.html" title="Class stack_context">Class <span class="emphasis"><em>stack_context</em></span></a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Boost.Context</strong></span> provides the class <span class="emphasis"><em>stack_context</em></span> + which will contain the stack pointer and the size of the stack. In case of + a <span class="emphasis"><em>segmented_stack</em></span>, <span class="emphasis"><em>stack_context</em></span> + contains some extra control structures. + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">stack_context</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="comment">// might contain additional control structures</span> + <span class="comment">// for segmented stacks</span> +<span class="special">}</span> +</pre> +<h5> +<a name="context.stack.stack_context.h0"></a> + <span class="phrase"><a name="context.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="stack_context.html#context.stack.stack_context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">sp</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Value:</span></dt> +<dd><p> + Pointer to the beginning of the stack. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.stack_context.h1"></a> + <span class="phrase"><a name="context.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="stack_context.html#context.stack.stack_context._code__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> + <span class="identifier">size</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Value:</span></dt> +<dd><p> + Actual size of the stack. + </p></dd> +</dl> +</div> +</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 © 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="stack_traits.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="valgrind.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/stack_traits.html b/libs/context/doc/html/context/stack/stack_traits.html new file mode 100644 index 000000000..a15f5f1be --- /dev/null +++ b/libs/context/doc/html/context/stack/stack_traits.html @@ -0,0 +1,158 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Class stack_traits</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="segmented.html" title="Class segmented_stack"> +<link rel="next" href="stack_context.html" title="Class stack_context"> +</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="segmented.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_context.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.stack_traits"></a><a class="link" href="stack_traits.html" title="Class stack_traits">Class <span class="emphasis"><em>stack_traits</em></span></a> +</h3></div></div></div> +<p> + <span class="emphasis"><em>stack_traits</em></span> models a <span class="emphasis"><em>stack-traits</em></span> + providing a way to access certain properites defined by the enironment. Stack + allocators use <span class="emphasis"><em>stack-traits</em></span> to allocate stacks. + </p> +<pre class="programlisting"><span class="preprocessor">#include</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">stack_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">stack_traits</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">is_unbounded</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">page_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">default_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">minimum_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">maximum_size</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<h5> +<a name="context.stack.stack_traits.h0"></a> + <span class="phrase"><a name="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__keyword__bool__phrase___phrase_role__identifier__is_unbounded__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">is_unbounded</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns <code class="computeroutput"><span class="keyword">true</span></code> if the environment + defines no limit for the size of a stack. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.stack_traits.h1"></a> + <span class="phrase"><a name="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__page_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">page_size</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the page size in bytes. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.stack_traits.h2"></a> + <span class="phrase"><a name="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__default_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">default_size</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns a default stack size, which may be platform specific. If the + stack is unbounded then the present implementation returns the maximum + of <code class="computeroutput"><span class="number">64</span> <span class="identifier">kB</span></code> + and <code class="computeroutput"><span class="identifier">minimum_size</span><span class="special">()</span></code>. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.stack_traits.h3"></a> + <span class="phrase"><a name="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__minimum_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">minimum_size</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the minimum size in bytes of stack defined by the environment + (Win32 4kB/Win64 8kB, defined by rlimit on POSIX). + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<h5> +<a name="context.stack.stack_traits.h4"></a> + <span class="phrase"><a name="context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="stack_traits.html#context.stack.stack_traits._code__phrase_role__keyword__static__phrase___phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__maximum_size__phrase__phrase_role__special______phrase___code_"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">maximum_size</span><span class="special">()</span></code></a> + </h5> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Preconditions:</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">is_unbounded</span><span class="special">()</span></code> + returns <code class="computeroutput"><span class="keyword">false</span></code>. + </p></dd> +<dt><span class="term">Returns:</span></dt> +<dd><p> + Returns the maximum size in bytes of stack defined by the environment. + </p></dd> +<dt><span class="term">Throws:</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +</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 © 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="segmented.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="stack_context.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context/stack/valgrind.html b/libs/context/doc/html/context/stack/valgrind.html new file mode 100644 index 000000000..e33e66f49 --- /dev/null +++ b/libs/context/doc/html/context/stack/valgrind.html @@ -0,0 +1,48 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Support for valgrind</title> +<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../../index.html" title="Chapter 1. Context"> +<link rel="up" href="../stack.html" title="Stack allocation"> +<link rel="prev" href="stack_context.html" title="Class stack_context"> +<link rel="next" href="../performance.html" title="Performance"> +</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="stack_context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="../performance.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="context.stack.valgrind"></a><a class="link" href="valgrind.html" title="Support for valgrind">Support for valgrind</a> +</h3></div></div></div> +<p> + Running programs that switch stacks under valgrind causes problems. Property + (b2 command-line) <code class="computeroutput"><span class="identifier">valgrind</span><span class="special">=</span><span class="identifier">on</span></code> let + valgrind treat the memory regions as stack space which suppresses the errors. + </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 © 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="stack_context.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stack.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="../performance.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/context/doc/html/context_HTML.manifest b/libs/context/doc/html/context_HTML.manifest index 354d0d6cb..c1d815723 100644 --- a/libs/context/doc/html/context_HTML.manifest +++ b/libs/context/doc/html/context_HTML.manifest @@ -2,7 +2,14 @@ index.html context/overview.html context/requirements.html context/context.html -context/context/boost_fcontext.html +context/econtext.html +context/stack.html +context/stack/protected_fixedsize.html +context/stack/fixedsize.html +context/stack/segmented.html +context/stack/stack_traits.html +context/stack/stack_context.html +context/stack/valgrind.html context/performance.html context/architectures.html context/rationale.html diff --git a/libs/context/doc/html/index.html b/libs/context/doc/html/index.html index e5fd35ba4..9efdf5967 100644 --- a/libs/context/doc/html/index.html +++ b/libs/context/doc/html/index.html @@ -25,7 +25,7 @@ <div><div class="author"><h3 class="author"> <span class="firstname">Oliver</span> <span class="surname">Kowalke</span> </h3></div></div> -<div><p class="copyright">Copyright © 2009 Oliver Kowalke</p></div> +<div><p class="copyright">Copyright © 2014 Oliver Kowalke</p></div> <div><div class="legalnotice"> <a name="context.legal"></a><p> Distributed under the Boost Software License, Version 1.0. (See accompanying @@ -38,9 +38,17 @@ <dl class="toc"> <dt><span class="section"><a href="context/overview.html">Overview</a></span></dt> <dt><span class="section"><a href="context/requirements.html">Requirements</a></span></dt> -<dt><span class="section"><a href="context/context.html">Context</a></span></dt> -<dd><dl><dt><span class="section"><a href="context/context/boost_fcontext.html"><code class="computeroutput"><span class="identifier">fcontext_t</span></code> - and related functions</a></span></dt></dl></dd> +<dt><span class="section"><a href="context/context.html">Struct fcontext_t</a></span></dt> +<dt><span class="section"><a href="context/econtext.html">Class execution_context</a></span></dt> +<dt><span class="section"><a href="context/stack.html">Stack allocation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="context/stack/protected_fixedsize.html">Class <span class="emphasis"><em>protected_fixedsize</em></span></a></span></dt> +<dt><span class="section"><a href="context/stack/fixedsize.html">Class <span class="emphasis"><em>fixedsize_stack</em></span></a></span></dt> +<dt><span class="section"><a href="context/stack/segmented.html">Class <span class="emphasis"><em>segmented_stack</em></span></a></span></dt> +<dt><span class="section"><a href="context/stack/stack_traits.html">Class <span class="emphasis"><em>stack_traits</em></span></a></span></dt> +<dt><span class="section"><a href="context/stack/stack_context.html">Class <span class="emphasis"><em>stack_context</em></span></a></span></dt> +<dt><span class="section"><a href="context/stack/valgrind.html">Support for valgrind</a></span></dt> +</dl></dd> <dt><span class="section"><a href="context/performance.html">Performance</a></span></dt> <dt><span class="section"><a href="context/architectures.html">Architectures</a></span></dt> <dt><span class="section"><a href="context/rationale.html">Rationale</a></span></dt> @@ -55,7 +63,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: October 30, 2014 at 10:14:04 GMT</small></p></td> +<td align="left"><p><small>Last revised: April 07, 2015 at 22:43:34 GMT</small></p></td> <td align="right"><div class="copyright-footer"></div></td> </tr></table> <hr> diff --git a/libs/context/doc/overview.qbk b/libs/context/doc/overview.qbk index 2db4aa841..e28104176 100644 --- a/libs/context/doc/overview.qbk +++ b/libs/context/doc/overview.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/performance.qbk b/libs/context/doc/performance.qbk index 83018130f..4ab1ee1b5 100644 --- a/libs/context/doc/performance.qbk +++ b/libs/context/doc/performance.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/rationale.qbk b/libs/context/doc/rationale.qbk index 966a7d4f5..a034f2ab4 100644 --- a/libs/context/doc/rationale.qbk +++ b/libs/context/doc/rationale.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/reference.qbk b/libs/context/doc/reference.qbk index d7ab1ddbd..8d498ce8a 100644 --- a/libs/context/doc/reference.qbk +++ b/libs/context/doc/reference.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/requirements.qbk b/libs/context/doc/requirements.qbk index 0621b2fcd..4c16ace19 100644 --- a/libs/context/doc/requirements.qbk +++ b/libs/context/doc/requirements.qbk @@ -1,5 +1,5 @@ [/ - Copyright Oliver Kowalke 2009. + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt diff --git a/libs/context/doc/stack.qbk b/libs/context/doc/stack.qbk index 5d179a7c6..b0461716f 100644 --- a/libs/context/doc/stack.qbk +++ b/libs/context/doc/stack.qbk @@ -1,4 +1,5 @@ -[/ Copyright Oliver Kowalke 2009. +[/ + Copyright Oliver Kowalke 2014. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt @@ -6,20 +7,294 @@ [section:stack Stack allocation] -A __fcontext__ requires a stack which will be allocated/deallocated -by a __stack_allocator__ (examples contain an implementation -of [@boost:/libs/context/example/simple_stack_allocator.hpp -simple_stack_allocator]). +The memory used by the stack is allocated/deallocated via a __stack_allocator__ +which is required to model a __stack_allocator_concept__. -[note The implementation of a __stack_allocator__ might include logic to protect + +[heading __stack_allocator_concept__] +A __stack_allocator__ must satisfy the __stack_allocator_concept__ requirements +shown in the following table, in which `a` is an object of a +__stack_allocator__ type, `sctx` is a `stack_context`, and `size` is a `std::size_t`: + +[table + [[expression][return type][notes]] + [ + [`a(size)`] + [] + [creates a stack allocator] + ] + [ + [`a.allocate()`] + [`stack_context`] + [creates a stack] + ] + [ + [`a.deallocate( sctx)`] + [`void`] + [deallocates the stack created by `a.allocate()`] + ] +] + +[important The implementation of `allocate()` might include logic to protect against exceeding the context's available stack size rather than leaving it as undefined behaviour.] +[important Calling `deallocate()` with a `stack_context` not set by `allocate()` +results in undefined behaviour.] + [note The stack is not required to be aligned; alignment takes place inside -__make_fcontext__.] +__econtext__.] -[note Depending on the architecture __stack_allocator__ returns an address from -the top of the stack (grows downwards) or the bottom of the stack (grows +[note Depending on the architecture `allocate()` stores an address from the +top of the stack (growing downwards) or the bottom of the stack (growing upwards).] + +[section:protected_fixedsize Class ['protected_fixedsize]] + +__boost_context__ provides the class __protected_fixedsize__ which models +the __stack_allocator_concept__. +It appends a guard page at the end of each stack to protect against exceeding +the stack. If the guard page is accessed (read or write operation) a +segmentation fault/access violation is generated by the operating system. + +[important Using __protected_fixedsize__ is expensive. That is, launching a +new coroutine with a new stack is expensive; the allocated stack is just as +efficient to use as any other stack.] + +[note The appended `guard page` is [*not] mapped to physical memory, only +virtual addresses are used.] + + #include <boost/context/protected_fixedsize.hpp> + + template< typename traitsT > + struct basic_protected_fixedsize + { + typedef traitT traits_type; + + basic_protected_fixesize(std::size_t size = traits_type::default_size()); + + stack_context allocate(); + + void deallocate( stack_context &); + } + + typedef basic_protected_fixedsize< stack_traits > protected_fixedsize + +[heading `stack_context allocate()`] +[variablelist +[[Preconditions:] [`traits_type::minimum:size() <= size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] +[[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer +to the stack and its actual size in `sctx`. Depending +on the architecture (the stack grows downwards/upwards) the stored address is +the highest/lowest address of the stack.]] +] + +[heading `void deallocate( stack_context & sctx)`] +[variablelist +[[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] +[[Effects:] [Deallocates the stack space.]] +] + +[endsect] + + +[section:fixedsize Class ['fixedsize_stack]] + +__boost_context__ provides the class __fixedsize__ which models +the __stack_allocator_concept__. +In contrast to __protected_fixedsize__ it does not append a guard page at the +end of each stack. The memory is simply managed by `std::malloc()` and +`std::free()`. + + #include <boost/context/fixedsize_stack.hpp> + + template< typename traitsT > + struct basic_fixedsize_stack + { + typedef traitT traits_type; + + basic_fixesize_stack(std::size_t size = traits_type::default_size()); + + stack_context allocate(); + + void deallocate( stack_context &); + } + + typedef basic_fixedsize_stack< stack_traits > fixedsize_stack; + +[heading `stack_context allocate()`] +[variablelist +[[Preconditions:] [`traits_type::minimum:size() <= size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] +[[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to +the stack and its actual size in `sctx`. Depending on the architecture (the +stack grows downwards/upwards) the stored address is the highest/lowest +address of the stack.]] +] + +[heading `void deallocate( stack_context & sctx)`] +[variablelist +[[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] +[[Effects:] [Deallocates the stack space.]] +] + +[endsect] + + +[section:segmented Class ['segmented_stack]] + +__boost_context__ supports usage of a __segmented__, e. g. the size of +the stack grows on demand. The coroutine is created with a minimal stack size +and will be increased as required. +Class __segmented__ models the __stack_allocator_concept__. +In contrast to __protected_fixedsize__ and __fixedsize__ it creates a +stack which grows on demand. + +[note Segmented stacks are currently only supported by [*gcc] from version +[*4.7] [*clang] from version [*3.4] onwards. In order to use a +__segmented_stack__ __boost_context__ must be built with +[*toolset=gcc segmented-stacks=on] at b2/bjam command-line. Applications +must be compiled with compiler-flags +[*-fsplit-stack -DBOOST_USE_SEGMENTED_STACKS].] + + #include <boost/context/segmented_stack.hpp> + + template< typename traitsT > + struct basic_segmented_stack + { + typedef traitT traits_type; + + basic_segmented_stack(std::size_t size = traits_type::default_size()); + + stack_context allocate(); + + void deallocate( stack_context &); + } + + typedef basic_segmented_stack< stack_traits > segmented_stack; + +[heading `stack_context allocate()`] +[variablelist +[[Preconditions:] [`traits_type::minimum:size() <= size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] +[[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to +the stack and its actual size in `sctx`. Depending on the architecture (the +stack grows downwards/upwards) the stored address is the highest/lowest +address of the stack.]] +] + +[heading `void deallocate( stack_context & sctx)`] +[variablelist +[[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and +`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] +[[Effects:] [Deallocates the stack space.]] +] + +[endsect] + + +[section:stack_traits Class ['stack_traits]] + +['stack_traits] models a __stack_traits__ providing a way to access certain +properites defined by the enironment. Stack allocators use __stack_traits__ to +allocate stacks. + + #include <boost/context/stack_traits.hpp> + + struct stack_traits + { + static bool is_unbounded() noexcept; + + static std::size_t page_size() noexcept; + + static std::size_t default_size() noexcept; + + static std::size_t minimum_size() noexcept; + + static std::size_t maximum_size() noexcept; + } + + +[heading `static bool is_unbounded()`] +[variablelist +[[Returns:] [Returns `true` if the environment defines no limit for the size of +a stack.]] +[[Throws:] [Nothing.]] +] + +[heading `static std::size_t page_size()`] +[variablelist +[[Returns:] [Returns the page size in bytes.]] +[[Throws:] [Nothing.]] +] + +[heading `static std::size_t default_size()`] +[variablelist +[[Returns:] [Returns a default stack size, which may be platform specific. +If the stack is unbounded then the present implementation returns the maximum of +`64 kB` and `minimum_size()`.]] +[[Throws:] [Nothing.]] +] + +[heading `static std::size_t minimum_size()`] +[variablelist +[[Returns:] [Returns the minimum size in bytes of stack defined by the +environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).]] +[[Throws:] [Nothing.]] +] + +[heading `static std::size_t maximum_size()`] +[variablelist +[[Preconditions:] [`is_unbounded()` returns `false`.]] +[[Returns:] [Returns the maximum size in bytes of stack defined by the +environment.]] +[[Throws:] [Nothing.]] +] + + +[endsect] + + +[section:stack_context Class ['stack_context]] + +__boost_context__ provides the class __stack_context__ which will contain +the stack pointer and the size of the stack. +In case of a __segmented__, __stack_context__ contains some extra control +structures. + + struct stack_context + { + void * sp; + std::size_t size; + + // might contain additional control structures + // for segmented stacks + } + +[heading `void * sp`] +[variablelist +[[Value:] [Pointer to the beginning of the stack.]] +] + +[heading `std::size_t size`] +[variablelist +[[Value:] [Actual size of the stack.]] +] + +[endsect] + + +[section:valgrind Support for valgrind] + +Running programs that switch stacks under valgrind causes problems. +Property (b2 command-line) `valgrind=on` let valgrind treat the memory regions +as stack space which suppresses the errors. + +[endsect] + + [endsect] |