boost/context
2
0
Fork 0
mirror of https://github.com/boostorg/context.git synced 2026-01-28 19:12:16 +00:00
Code Issues Projects Releases Wiki Activity
Files
9ed3c19900f9acd517cba61fbca962a9bf90323e
context/doc/context.xml
Oliver Kowalke fac5cc5e12 fix type in docu
2014-01-17 17:34:47 +01:00

1173 lines
72 KiB
XML
Raw Blame History

<?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: 2014/01/17 16:33:51 $"
xmlns:xi="http://www.w3.org/2001/XInclude">
<libraryinfo>
<authorgroup>
<author>
<firstname>Oliver</firstname> <surname>Kowalke</surname>
</author>
</authorgroup>
<copyright>
<year>2009</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 fewer than hundred 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">&lt;</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">&gt;</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 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">Context</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 &quot;C&quot;.
</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 and manages a protected stack (with guard page)</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase> <phrase role="identifier">alloc</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">alloc</phrase><phrase role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase role="special">(</phrase><phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</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">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</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="special">*</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="keyword">namespace</phrase> <phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="special">*</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</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">&lt;&lt;</phrase> <phrase role="string">&quot;f1: entered&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;f1: call jump_fcontext( fc1, fc2, 0)&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">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">&lt;&lt;</phrase> <phrase role="string">&quot;f1: return&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</phrase> <phrase role="special">&amp;</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">&lt;&lt;</phrase> <phrase role="string">&quot;f2: entered&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;f2: call jump_fcontext( fc2, fc1, 0)&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">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">&amp;&amp;</phrase> <phrase role="special">!</phrase> <phrase role="string">&quot;f2: never returns&quot;</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="keyword">int</phrase> <phrase role="identifier">argc</phrase><phrase role="special">,</phrase> <phrase role="keyword">char</phrase> <phrase role="special">*</phrase> <phrase role="identifier">argv</phrase><phrase role="special">[])</phrase>
<phrase role="special">{</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase> <phrase role="identifier">alloc</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">alloc</phrase><phrase role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase role="special">(</phrase><phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</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">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</phrase><phrase role="special">());</phrase>
<phrase role="identifier">fc1</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</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">ctx</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">&lt;&lt;</phrase> <phrase role="string">&quot;main: call jump_fcontext( &amp; fcm, fc1, 0)&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&amp;</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">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;main: done&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="keyword">return</phrase> <phrase role="identifier">EXIT_SUCCESS</phrase><phrase role="special">;</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">&amp;</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="special">&amp;</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">&amp;</phrase> <phrase role="identifier">fc1</phrase><phrase role="special">,</phrase> <phrase role="special">&amp;</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">&amp;</phrase> <phrase role="identifier">fc2</phrase><phrase role="special">,</phrase> <phrase role="special">&amp;</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>
<phrase role="identifier">main</phrase><phrase role="special">:</phrase> <phrase role="identifier">done</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="keyword">namespace</phrase> <phrase role="identifier">ctx</phrase> <phrase role="special">=</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">;</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">fcontext_t</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</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">&lt;</phrase> <phrase role="keyword">int</phrase><phrase role="special">,</phrase> <phrase role="keyword">int</phrase> <phrase role="special">&gt;</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="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="special">(</phrase> <phrase role="identifier">pair_t</phrase> <phrase role="special">*)</phrase> <phrase role="identifier">ctx</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="special">&amp;</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="special">(</phrase> <phrase role="identifier">intptr_t</phrase><phrase role="special">)</phrase> <phrase role="special">(</phrase> <phrase role="identifier">p</phrase><phrase role="special">-&gt;</phrase><phrase role="identifier">first</phrase> <phrase role="special">+</phrase> <phrase role="identifier">p</phrase><phrase role="special">-&gt;</phrase><phrase role="identifier">second</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase>
<phrase role="identifier">ctx</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="special">&amp;</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="special">(</phrase> <phrase role="identifier">intptr_t</phrase><phrase role="special">)</phrase> <phrase role="special">(</phrase> <phrase role="identifier">p</phrase><phrase role="special">-&gt;</phrase><phrase role="identifier">first</phrase> <phrase role="special">+</phrase> <phrase role="identifier">p</phrase><phrase role="special">-&gt;</phrase><phrase role="identifier">second</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="keyword">int</phrase> <phrase role="identifier">argc</phrase><phrase role="special">,</phrase> <phrase role="keyword">char</phrase> <phrase role="special">*</phrase> <phrase role="identifier">argv</phrase><phrase role="special">[])</phrase>
<phrase role="special">{</phrase>
<phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase> <phrase role="identifier">alloc</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">alloc</phrase><phrase role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase role="special">(</phrase><phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</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">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">guarded_stack_allocator</phrase><phrase role="special">::</phrase><phrase role="identifier">minimum_stacksize</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="special">);</phrase>
<phrase role="identifier">fc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ctx</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="special">(</phrase> <phrase role="keyword">int</phrase><phrase role="special">)</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&amp;</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="identifier">fc</phrase><phrase role="special">,</phrase> <phrase role="special">(</phrase> <phrase role="identifier">intptr_t</phrase><phrase role="special">)</phrase> <phrase role="special">&amp;</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">&lt;&lt;</phrase> <phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">first</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot; + &quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">second</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot; == &quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">res</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">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="special">(</phrase> <phrase role="keyword">int</phrase><phrase role="special">)</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">::</phrase><phrase role="identifier">jump_fcontext</phrase><phrase role="special">(</phrase> <phrase role="special">&amp;</phrase> <phrase role="identifier">fcm</phrase><phrase role="special">,</phrase> <phrase role="identifier">fc</phrase><phrase role="special">,</phrase> <phrase role="special">(</phrase> <phrase role="identifier">intptr_t</phrase><phrase role="special">)</phrase> <phrase role="special">&amp;</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">&lt;&lt;</phrase> <phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">first</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot; + &quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">p</phrase><phrase role="special">.</phrase><phrase role="identifier">second</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot; == &quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">res</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;main: done&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
<phrase role="keyword">return</phrase> <phrase role="identifier">EXIT_SUCCESS</phrase><phrase role="special">;</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>
<phrase role="identifier">main</phrase><phrase role="special">:</phrase> <phrase role="identifier">done</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>
<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>
<section id="context.context.boost_fcontext">
<title><link linkend="context.context.boost_fcontext">Struct <code><phrase
role="identifier">fcontext_t</phrase></code> and related functions</link></title>
<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">struct</phrase> <phrase role="identifier">fcontext_t</phrase>
<phrase role="special">{</phrase>
<phrase role="special">&lt;</phrase> <phrase role="identifier">platform</phrase> <phrase role="identifier">specific</phrase> <phrase role="special">&gt;</phrase>
<phrase role="identifier">stack_t</phrase> <phrase role="identifier">fc_stack</phrase><phrase role="special">;</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="keyword">const</phrase><phrase role="special">*</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="special">*</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> <phrase role="special">);</phrase>
</programlisting>
<bridgehead renderas="sect4" id="context.context.boost_fcontext.h0">
<phrase id="context.context.boost_fcontext._code__phrase_role__identifier__sp__phrase___code_"/><link
linkend="context.context.boost_fcontext._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="sect4" id="context.context.boost_fcontext.h1">
<phrase id="context.context.boost_fcontext._code__phrase_role__identifier__size__phrase___code_"/><link
linkend="context.context.boost_fcontext._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="sect4" id="context.context.boost_fcontext.h2">
<phrase id="context.context.boost_fcontext._code__phrase_role__identifier__fc_stack__phrase___code_"/><link
linkend="context.context.boost_fcontext._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="sect4" id="context.context.boost_fcontext.h3">
<phrase id="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__special_____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.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__special_____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="special">*</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="special">*</phrase><phrase role="identifier">nfc</phrase></code>,
which implies jumping to <code><phrase role="special">*</phrase><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="sect4" id="context.context.boost_fcontext.h4">
<phrase id="context.context.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__special_____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.boost_fcontext._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__special_____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="special">*</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> 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>
&gt; 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effects:</term>
<listitem>
<para>
Creates an fcontext_t at the beginning 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 pointer to fcontext_t which is placed on the stack.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section id="context.stack">
<title><link linkend="context.stack">Stack allocation</link></title>
<para>
A <emphasis>fcontext_t</emphasis> requires a stack which will be allocated/deallocated
by a <emphasis>StackAllocator</emphasis> (examples contain an implementation
of <ulink url="boost:/libs/context/example/simple_stack_allocator.hpp">simple_stack_allocator</ulink>).
</para>
<note>
<para>
The implementation of a <emphasis>StackAllocator</emphasis> might include
logic to protect against exceeding the context's available stack size rather
than leaving it as undefined behaviour.
</para>
</note>
<note>
<para>
The stack is not required to be aligned; alignment takes place inside <emphasis>make_fcontext()</emphasis>.
</para>
</note>
<note>
<para>
Depending on the architecture <emphasis>StackAllocator</emphasis> returns
an address from the top of the stack (grows downwards) or the bottom of the
stack (grows upwards).
</para>
</note>
</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.architectues">
<title><link linkend="context.architectues">Architectures</link></title>
<para>
<emphasis role="bold">Boost.Context</emphasis> supports following architectures:
</para>
<table frame="all" id="context.architectues.supported_architectures___abi_binary_format__">
<title>Supported architectures (&lt;ABI|binary format&gt;)</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>
SYSV|ELF
</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>
Because the assembler code uses the byte layout of <emphasis>fcontext_t</emphasis>
to access its members <emphasis>fcontext_t</emphasis> must be a POD. This requires
that <emphasis>fcontext_t</emphasis> has only a default constructor, no visibility
keywords (e.g. private, public, protected), no virtual methods and all members
and base classes are PODs too.
</para>
<bridgehead renderas="sect3" id="context.rationale.h2">
<phrase id="context.rationale.protecting_the_stack"/><link linkend="context.rationale.protecting_the_stack">Protecting
the stack</link>
</bridgehead>
<para>
Because the stack's size is fixed -- there is no support for split stacks yet
-- it is important to protect against exceeding the stack's bounds. Otherwise,
in the best case, overrunning the stack's memory will result in a segmentation
fault or access violation and, in the worst case, the application's memory
will be overwritten. <code><phrase role="identifier">stack_allocator</phrase></code>
appends a guard page to the stack to help detect overruns. The guard page consumes
no physical memory, but generates a segmentation fault or access violation
on access to the virtual memory addresses within it.
</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">&gt;=</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">&gt;=</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>
&quot;The FpCsr and the MxCsr register must be saved and restored before
any call or return by any procedure that needs to modify them ...&quot;
<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 - &quot;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 ...&quot; <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 - &quot;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 ...&quot; <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>
&quot;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.&quot; <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>
&quot;The 64-bit Microsoft compiler does not use ST(0)-ST(7)/MM0-MM7&quot;.
<footnote id="context.rationale.x86_and_floating_point_env.f4">
<para>
'Calling Conventions', Agner Fog
</para>
</footnote>.
</para>
<para>
&quot;XMM6-XMM15 must be preserved&quot; <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>
&quot;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.&quot; <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.todo">
<title><link linkend="context.todo">Todo</link></title>
<itemizedlist>
<listitem>
<simpara>
provide support for SPARC, SuperH (SH4), S/390
</simpara>
</listitem>
<listitem>
<simpara>
support split-stack feature from gcc/gold linker
</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>
Reference in New Issue View Git Blame Copy Permalink