fix docu
This commit is contained in:
Oliver Kowalke
parent
06a46e8db1
commit
47329c468a
941
doc/context.xml
Normal file
941
doc/context.xml
Normal file
@ -0,0 +1,941 @@
|
||||
<?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/16 17:01:37 $"
|
||||
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"><</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 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 "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 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"><<</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">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"><<</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">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">&</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">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">&&</phrase> <phrase role="special">!</phrase> <phrase role="string">"f2: never returns"</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"><<</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">ctx</phrase><phrase role="special">::</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">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"main: 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="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">&</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="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="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="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>
|
||||
<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"><</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="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">&</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">-></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">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">&</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">-></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="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">&</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">&</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="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">&</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">&</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">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"main: 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="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"><</phrase> <phrase role="identifier">platform</phrase> <phrase role="identifier">specific</phrase> <phrase role="special">></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>
|
||||
> 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.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">>=</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.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>
|
||||
49
doc/html/context/acknowledgements.html
Normal file
49
doc/html/context/acknowledgements.html
Normal file
@ -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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="todo.html" title="Todo">
|
||||
</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="todo.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>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="context.acknowledgements"></a><a class="link" href="acknowledgements.html" title="Acknowledgments">Acknowledgments</a>
|
||||
</h2></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 © 2009 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="todo.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>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
303
doc/html/context/context.html
Normal file
303
doc/html/context/context.html
Normal file
@ -0,0 +1,303 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="requirements.html" title="Requirements">
|
||||
<link rel="next" href="context/boost_fcontext.html" title="Struct fcontext_t and related functions">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="requirements.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="context/boost_fcontext.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>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl><dt><span class="section"><a href="context/boost_fcontext.html">Struct <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>
|
||||
and <span class="emphasis"><em>make_fcontext()</em></span> it provides a execution control transfer
|
||||
mechanism similar interface like <a href="http://www.kernel.org/doc/man-pages/online/pages/man2/getcontext.2.html" target="_top">ucontext_t</a>.
|
||||
<span class="emphasis"><em>fcontext_t</em></span> and its functions are located in <span class="emphasis"><em>boost::context</em></span>
|
||||
and the functions are declared as extern "C".
|
||||
</p>
|
||||
<div class="warning"><table border="0" summary="Warning">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
|
||||
<th align="left">Warning</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
If <span class="emphasis"><em>fcontext_t</em></span> is used in a multi threaded application,
|
||||
it can migrated between threads, but must not reference <span class="emphasis"><em>thread-local
|
||||
storage</em></span>.
|
||||
</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>
|
||||
The low level API is the part to port to new platforms.
|
||||
</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>
|
||||
If <span class="emphasis"><em>fiber-local storage</em></span> is used on Windows, the user
|
||||
is responsible for calling <span class="emphasis"><em>::FlsAlloc()</em></span>, <span class="emphasis"><em>::FlsFree()</em></span>.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<h4>
|
||||
<a name="context.context.h0"></a>
|
||||
<span><a name="context.context.executing_a_context"></a></span><a class="link" href="context.html#context.context.executing_a_context">Executing
|
||||
a context</a>
|
||||
</h4>
|
||||
<p>
|
||||
A new context supposed to execute a <span class="emphasis"><em>context-function</em></span> (returning
|
||||
void and accepting intptr_t as argument) will be created on top of the stack
|
||||
(at 16 byte boundary) by function <span class="emphasis"><em>make_fcontext()</em></span>.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// context-function</span>
|
||||
<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span> <span class="identifier">intptr</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// creates and manages a protected stack (with guard page)</span>
|
||||
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span> <span class="identifier">alloc</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">alloc</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">minimum_stacksize</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">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span><span class="special">::</span><span class="identifier">minimum_stacksize</span><span class="special">());</span>
|
||||
|
||||
<span class="comment">// context fc uses f() as context function</span>
|
||||
<span class="comment">// fcontext_t is placed on top of context stack</span>
|
||||
<span class="comment">// a pointer to fcontext_t is returned</span>
|
||||
<span class="identifier">fcontext_t</span> <span class="special">*</span> <span class="identifier">fc</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>
|
||||
</pre>
|
||||
<p>
|
||||
Calling <span class="emphasis"><em>jump_fcontext()</em></span> invokes the <span class="emphasis"><em>context-function</em></span>
|
||||
in a newly created context complete with registers, flags, stack and instruction
|
||||
pointers. When control should be returned to the original calling context,
|
||||
call <span class="emphasis"><em>jump_fcontext()</em></span>. The current context information
|
||||
(registers, flags, and stack and instruction pointers) is saved and the original
|
||||
context information is restored. Calling <span class="emphasis"><em>jump_fcontext()</em></span>
|
||||
again resumes execution in the second context after saving the new state of
|
||||
the original context.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fcontext_t</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">fc2</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">f1</span><span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"f1: entered"</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">"f1: call jump_fcontext( fc1, fc2, 0)"</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">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="identifier">fc2</span><span class="special">,</span> <span class="number">0</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">"f1: return"</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">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">f2</span><span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"f2: entered"</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">"f2: call jump_fcontext( fc2, fc1, 0)"</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">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="identifier">fc2</span><span class="special">,</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="identifier">BOOST_ASSERT</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">&&</span> <span class="special">!</span> <span class="string">"f2: never returns"</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="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span> <span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span> <span class="identifier">alloc</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">alloc</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">minimum_stacksize</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">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span><span class="special">::</span><span class="identifier">minimum_stacksize</span><span class="special">());</span>
|
||||
|
||||
<span class="identifier">fc1</span> <span class="special">=</span> <span class="identifier">ctx</span><span class="special">::</span><span class="identifier">make_fcontext</span><span class="special">(</span> <span class="identifier">sp1</span><span class="special">,</span> <span class="identifier">size</span><span class="special">,</span> <span class="identifier">f1</span><span class="special">);</span>
|
||||
<span class="identifier">fc2</span> <span class="special">=</span> <span class="identifier">ctx</span><span class="special">::</span><span class="identifier">make_fcontext</span><span class="special">(</span> <span class="identifier">sp2</span><span class="special">,</span> <span class="identifier">size</span><span class="special">,</span> <span class="identifier">f2</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"main: call jump_fcontext( & fcm, fc1, 0)"</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">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="number">0</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">"main: 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="keyword">return</span> <span class="identifier">EXIT_SUCCESS</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="identifier">output</span><span class="special">:</span>
|
||||
<span class="identifier">main</span><span class="special">:</span> <span class="identifier">call</span> <span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="special">&</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">entered</span>
|
||||
<span class="identifier">f1</span><span class="special">:</span> <span class="identifier">call</span> <span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="special">&</span> <span class="identifier">fc2</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">f2</span><span class="special">:</span> <span class="identifier">entered</span>
|
||||
<span class="identifier">f2</span><span class="special">:</span> <span class="identifier">call</span> <span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fc2</span><span class="special">,</span> <span class="special">&</span> <span class="identifier">fc1</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">f1</span><span class="special">:</span> <span class="keyword">return</span>
|
||||
<span class="identifier">main</span><span class="special">:</span> <span class="identifier">done</span>
|
||||
</pre>
|
||||
<p>
|
||||
First call of <span class="emphasis"><em>jump_fcontext()</em></span> enters the <span class="emphasis"><em>context-function</em></span>
|
||||
<code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>
|
||||
by starting context fc1 (context fcm saves the registers of <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>). For jumping between context's fc1 and fc2
|
||||
<code class="computeroutput"><span class="identifier">jump_fcontext</span><span class="special">()</span></code>
|
||||
is called. Because context fcm is chained to fc1, <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code> is entered (returning from <span class="emphasis"><em>jump_fcontext()</em></span>)
|
||||
after context fc1 becomes complete (return from <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>).
|
||||
</p>
|
||||
<div class="warning"><table border="0" summary="Warning">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
|
||||
<th align="left">Warning</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
Calling <span class="emphasis"><em>jump_fcontext()</em></span> to the same context from inside
|
||||
the same context results in 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>
|
||||
The size of the stack is required to be larger than the size of fcontext_t.
|
||||
</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>
|
||||
In contrast to threads, which are preemtive, <span class="emphasis"><em>fcontext_t</em></span>
|
||||
switches are cooperative (programmer controls when switch will happen). The
|
||||
kernel is not involved in the context switches.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<h4>
|
||||
<a name="context.context.h1"></a>
|
||||
<span><a name="context.context.transfer_of_data"></a></span><a class="link" href="context.html#context.context.transfer_of_data">Transfer
|
||||
of data</a>
|
||||
</h4>
|
||||
<p>
|
||||
The third argument passed to <span class="emphasis"><em>jump_fcontext()</em></span>, in one context,
|
||||
is passed as the first argument of the <span class="emphasis"><em>context-function</em></span>
|
||||
if the context is started for the first time. In all following invocations
|
||||
of <span class="emphasis"><em>jump_fcontext()</em></span> the intptr_t passed to <span class="emphasis"><em>jump_fcontext()</em></span>,
|
||||
in one context, is returned by <span class="emphasis"><em>jump_fcontext()</em></span> in the
|
||||
other context.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">ctx</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">fcontext_t</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">fc</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span> <span class="special">></span> <span class="identifier">pair_t</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span> <span class="identifier">intptr_t</span> <span class="identifier">param</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">pair_t</span> <span class="special">*</span> <span class="identifier">p</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">pair_t</span> <span class="special">*)</span> <span class="identifier">param</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">p</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">pair_t</span> <span class="special">*)</span> <span class="identifier">ctx</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="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</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">ctx</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="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</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="special">}</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span> <span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span> <span class="identifier">alloc</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">alloc</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="identifier">ctx</span><span class="special">::</span><span class="identifier">minimum_stacksize</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">ctx</span><span class="special">::</span><span class="identifier">guarded_stack_allocator</span><span class="special">::</span><span class="identifier">minimum_stacksize</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="special">);</span>
|
||||
<span class="identifier">fc</span> <span class="special">=</span> <span class="identifier">ctx</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>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">res</span> <span class="special">=</span> <span class="special">(</span> <span class="keyword">int</span><span class="special">)</span> <span class="identifier">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="identifier">fc</span><span class="special">,</span> <span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</span> <span class="special">&</span> <span class="identifier">p</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">p</span><span class="special">.</span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">" + "</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="string">" == "</span> <span class="special"><<</span> <span class="identifier">res</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">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">5</span><span class="special">,</span> <span class="number">6</span><span class="special">);</span>
|
||||
<span class="identifier">res</span> <span class="special">=</span> <span class="special">(</span> <span class="keyword">int</span><span class="special">)</span> <span class="identifier">ctx</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(</span> <span class="special">&</span> <span class="identifier">fcm</span><span class="special">,</span> <span class="identifier">fc</span><span class="special">,</span> <span class="special">(</span> <span class="identifier">intptr_t</span><span class="special">)</span> <span class="special">&</span> <span class="identifier">p</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">p</span><span class="special">.</span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">" + "</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="string">" == "</span> <span class="special"><<</span> <span class="identifier">res</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">"main: 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="keyword">return</span> <span class="identifier">EXIT_SUCCESS</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="identifier">output</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="number">9</span>
|
||||
<span class="number">5</span> <span class="special">+</span> <span class="number">6</span> <span class="special">==</span> <span class="number">11</span>
|
||||
<span class="identifier">main</span><span class="special">:</span> <span class="identifier">done</span>
|
||||
</pre>
|
||||
<h4>
|
||||
<a name="context.context.h2"></a>
|
||||
<span><a name="context.context.exceptions_in__emphasis_context_function__emphasis_"></a></span><a class="link" href="context.html#context.context.exceptions_in__emphasis_context_function__emphasis_">Exceptions
|
||||
in <span class="emphasis"><em>context-function</em></span></a>
|
||||
</h4>
|
||||
<p>
|
||||
If the <span class="emphasis"><em>context-function</em></span> emits an exception, the behaviour
|
||||
is undefined.
|
||||
</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>
|
||||
<span class="emphasis"><em>context-function</em></span> should wrap the code in a try/catch
|
||||
block.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<h4>
|
||||
<a name="context.context.h3"></a>
|
||||
<span><a name="context.context.preserving_floating_point_registers"></a></span><a class="link" href="context.html#context.context.preserving_floating_point_registers">Preserving
|
||||
floating point registers</a>
|
||||
</h4>
|
||||
<p>
|
||||
Preserving the floating point registers increases the cycle count for a context
|
||||
switch (see performance tests). The fourth argument of <span class="emphasis"><em>jump_fcontext()</em></span>
|
||||
controls if fpu registers should be preserved by the context jump.
|
||||
</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>
|
||||
The use of the fpu controlling argument of <span class="emphasis"><em>jump_fcontext()</em></span>
|
||||
must be consistent in the application. Otherwise the behaviour is undefined.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<h4>
|
||||
<a name="context.context.h4"></a>
|
||||
<span><a name="context.context.stack_unwinding"></a></span><a class="link" href="context.html#context.context.stack_unwinding">Stack
|
||||
unwinding</a>
|
||||
</h4>
|
||||
<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>
|
||||
</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>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="requirements.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="context/boost_fcontext.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
156
doc/html/context/context/boost_fcontext.html
Normal file
156
doc/html/context/context/boost_fcontext.html
Normal file
@ -0,0 +1,156 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Struct 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.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="../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="../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="../stack.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.context.boost_fcontext"></a><a class="link" href="boost_fcontext.html" title="Struct fcontext_t and related functions">Struct <code class="computeroutput"><span class="identifier">fcontext_t</span></code> and related functions</a>
|
||||
</h3></div></div></div>
|
||||
<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">struct</span> <span class="identifier">fcontext_t</span>
|
||||
<span class="special">{</span>
|
||||
<span class="special"><</span> <span class="identifier">platform</span> <span class="identifier">specific</span> <span class="special">></span>
|
||||
|
||||
<span class="identifier">stack_t</span> <span class="identifier">fc_stack</span><span class="special">;</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="keyword">const</span><span class="special">*</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="special">*</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> <span class="special">);</span>
|
||||
</pre>
|
||||
<h5>
|
||||
<a name="context.context.boost_fcontext.h0"></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>
|
||||
<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>
|
||||
<h5>
|
||||
<a name="context.context.boost_fcontext.h1"></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>
|
||||
<dt><span class="term">Member:</span></dt>
|
||||
<dd><p>
|
||||
Size of the stack in bytes.
|
||||
</p></dd>
|
||||
</dl>
|
||||
</div>
|
||||
<h5>
|
||||
<a name="context.context.boost_fcontext.h2"></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>
|
||||
<dt><span class="term">Member:</span></dt>
|
||||
<dd><p>
|
||||
Tracks the memory for the context's stack.
|
||||
</p></dd>
|
||||
</dl>
|
||||
</div>
|
||||
<h5>
|
||||
<a name="context.context.boost_fcontext.h3"></a>
|
||||
<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__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_"></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__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 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="special">*</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>
|
||||
<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="special">*</span><span class="identifier">nfc</span></code>,
|
||||
which implies jumping to <code class="computeroutput"><span class="special">*</span><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>
|
||||
<h5>
|
||||
<a name="context.context.boost_fcontext.h4"></a>
|
||||
<span><a name="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_"></a></span><a class="link" href="boost_fcontext.html#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 class="computeroutput"><span class="identifier">fcontext_t</span> <span class="special">*</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>
|
||||
<dt><span class="term">Precondition:</span></dt>
|
||||
<dd><p>
|
||||
Stack <code class="computeroutput"><span class="identifier">sp</span></code> 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 at the beginning 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 pointer to 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>
|
||||
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="../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="../stack.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
83
doc/html/context/overview.html
Normal file
83
doc/html/context/overview.html
Normal file
@ -0,0 +1,83 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Overview</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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="../index.html" title="Chapter 1. Context">
|
||||
<link rel="next" href="requirements.html" title="Requirements">
|
||||
</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="../index.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="requirements.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.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
<span class="bold"><strong>Boost.Context</strong></span> 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 <span class="emphasis"><em>fcontext_t</em></span> instance represents
|
||||
a specific point in the application's execution path. This is useful for building
|
||||
higher-level abstractions, like <span class="emphasis"><em>coroutines</em></span>, <span class="emphasis"><em>cooperative
|
||||
threads (userland threads)</em></span> or an equivalent to <a href="http://msdn.microsoft.com/en-us/library/9k7k7cf0%28v=vs.80%29.aspx" target="_top">C#
|
||||
keyword <span class="emphasis"><em>yield</em></span></a> in C++.
|
||||
</p>
|
||||
<p>
|
||||
A <span class="emphasis"><em>fcontext_t</em></span> provides the means to suspend the current
|
||||
execution path and to transfer execution control, thereby permitting another
|
||||
<span class="emphasis"><em>fcontext_t</em></span> to run on the current thread. This state full
|
||||
transfer mechanism enables a <span class="emphasis"><em>fcontext_t</em></span> to suspend execution
|
||||
from within nested functions and, later, to resume from where it was suspended.
|
||||
While the execution path represented by a <span class="emphasis"><em>fcontext_t</em></span> only
|
||||
runs on a single thread, it can be migrated to another thread at any given
|
||||
time.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
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:
|
||||
</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">all</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
which includes all the other headers in turn.
|
||||
</p>
|
||||
<p>
|
||||
All functions and classes are contained in the namespace <span class="emphasis"><em>boost::context</em></span>.
|
||||
</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 © 2009 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="../index.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="requirements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
139
doc/html/context/performance.html
Normal file
139
doc/html/context/performance.html
Normal file
@ -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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="stack.html" title="Stack allocation">
|
||||
<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="stack.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="rationale.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.performance"></a><a class="link" href="performance.html" title="Performance">Performance</a>
|
||||
</h2></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.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.performance.f0" href="#ftn.context.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.performance.f1" href="#ftn.context.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.performance.f0" href="#context.performance.f0" class="para">a</a>] </sup>
|
||||
AMD Athlon 64 DualCore 4400+
|
||||
</p></div>
|
||||
<div class="footnote"><p><sup>[<a name="ftn.context.performance.f1" href="#context.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 © 2009 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="../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="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
105
doc/html/context/rationale.html
Normal file
105
doc/html/context/rationale.html
Normal file
@ -0,0 +1,105 @@
|
||||
<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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="performance.html" title="Performance">
|
||||
<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="performance.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="rationale/other_apis_.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.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
|
||||
</h2></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>
|
||||
<h4>
|
||||
<a name="context.rationale.h0"></a>
|
||||
<span><a name="context.rationale.no_inline_assembler"></a></span><a class="link" href="rationale.html#context.rationale.no_inline_assembler">No
|
||||
inline-assembler</a>
|
||||
</h4>
|
||||
<p>
|
||||
Some newer compiler (for instance MSVC 10 for x86_64 and itanium) do not support
|
||||
inline assembler. <sup>[<a name="context.rationale.f0" href="#ftn.context.rationale.f0" class="footnote">1</a>]</sup>. Inlined assembler generates code bloating which his not welcome
|
||||
on embedded systems.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="context.rationale.h1"></a>
|
||||
<span><a name="context.rationale.fcontext_t"></a></span><a class="link" href="rationale.html#context.rationale.fcontext_t">fcontext_t</a>
|
||||
</h4>
|
||||
<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>
|
||||
Because the assembler code uses the byte layout of <span class="emphasis"><em>fcontext_t</em></span>
|
||||
to access its members <span class="emphasis"><em>fcontext_t</em></span> must be a POD. This requires
|
||||
that <span class="emphasis"><em>fcontext_t</em></span> 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.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="context.rationale.h2"></a>
|
||||
<span><a name="context.rationale.protecting_the_stack"></a></span><a class="link" href="rationale.html#context.rationale.protecting_the_stack">Protecting
|
||||
the stack</a>
|
||||
</h4>
|
||||
<p>
|
||||
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 class="computeroutput"><span class="identifier">stack_allocator</span></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.
|
||||
</p>
|
||||
<div class="footnotes">
|
||||
<br><hr width="100" align="left">
|
||||
<div class="footnote"><p><sup>[<a name="ftn.context.rationale.f0" href="#context.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 © 2009 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="../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="rationale/other_apis_.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
117
doc/html/context/rationale/other_apis_.html
Normal file
117
doc/html/context/rationale/other_apis_.html
Normal file
@ -0,0 +1,117 @@
|
||||
<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><h3 class="title">
|
||||
<a name="context.rationale.other_apis_"></a><a class="link" href="other_apis_.html" title="Other APIs">Other APIs </a>
|
||||
</h3></div></div></div>
|
||||
<h5>
|
||||
<a name="context.rationale.other_apis_.h0"></a>
|
||||
<span><a name="context.rationale.other_apis_.setjmp___longjmp__"></a></span><a class="link" href="other_apis_.html#context.rationale.other_apis_.setjmp___longjmp__">setjmp()/longjmp()</a>
|
||||
</h5>
|
||||
<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.rationale.other_apis_.f0" href="#ftn.context.rationale.other_apis_.f0" class="footnote">2</a>]</sup>.
|
||||
</p>
|
||||
<h5>
|
||||
<a name="context.rationale.other_apis_.h1"></a>
|
||||
<span><a name="context.rationale.other_apis_.ucontext_t"></a></span><a class="link" href="other_apis_.html#context.rationale.other_apis_.ucontext_t">ucontext_t</a>
|
||||
</h5>
|
||||
<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.rationale.other_apis_.f1" href="#ftn.context.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>
|
||||
<h5>
|
||||
<a name="context.rationale.other_apis_.h2"></a>
|
||||
<span><a name="context.rationale.other_apis_.windows_fibers"></a></span><a class="link" href="other_apis_.html#context.rationale.other_apis_.windows_fibers">Windows
|
||||
fibers</a>
|
||||
</h5>
|
||||
<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.rationale.other_apis_.f0" href="#context.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.rationale.other_apis_.f1" href="#context.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 © 2009 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>
|
||||
124
doc/html/context/rationale/x86_and_floating_point_env.html
Normal file
124
doc/html/context/rationale/x86_and_floating_point_env.html
Normal file
@ -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><h3 class="title">
|
||||
<a name="context.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>
|
||||
</h3></div></div></div>
|
||||
<h5>
|
||||
<a name="context.rationale.x86_and_floating_point_env.h0"></a>
|
||||
<span><a name="context.rationale.x86_and_floating_point_env.i386"></a></span><a class="link" href="x86_and_floating_point_env.html#context.rationale.x86_and_floating_point_env.i386">i386</a>
|
||||
</h5>
|
||||
<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.rationale.x86_and_floating_point_env.f0" href="#ftn.context.rationale.x86_and_floating_point_env.f0" class="footnote">4</a>]</sup>.
|
||||
</p>
|
||||
<h5>
|
||||
<a name="context.rationale.x86_and_floating_point_env.h1"></a>
|
||||
<span><a name="context.rationale.x86_and_floating_point_env.x86_64"></a></span><a class="link" href="x86_and_floating_point_env.html#context.rationale.x86_and_floating_point_env.x86_64">x86_64</a>
|
||||
</h5>
|
||||
<h5>
|
||||
<a name="context.rationale.x86_and_floating_point_env.h2"></a>
|
||||
<span><a name="context.rationale.x86_and_floating_point_env.windows"></a></span><a class="link" href="x86_and_floating_point_env.html#context.rationale.x86_and_floating_point_env.windows">Windows</a>
|
||||
</h5>
|
||||
<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.rationale.x86_and_floating_point_env.f1" href="#ftn.context.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.rationale.x86_and_floating_point_env.f2" href="#ftn.context.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.rationale.x86_and_floating_point_env.f3" href="#ftn.context.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.rationale.x86_and_floating_point_env.f4" href="#ftn.context.rationale.x86_and_floating_point_env.f4" class="footnote">8</a>]</sup>.
|
||||
</p>
|
||||
<p>
|
||||
"XMM6-XMM15 must be preserved" <sup>[<a name="context.rationale.x86_and_floating_point_env.f5" href="#ftn.context.rationale.x86_and_floating_point_env.f5" class="footnote">9</a>]</sup>
|
||||
</p>
|
||||
<h5>
|
||||
<a name="context.rationale.x86_and_floating_point_env.h3"></a>
|
||||
<span><a name="context.rationale.x86_and_floating_point_env.sysv"></a></span><a class="link" href="x86_and_floating_point_env.html#context.rationale.x86_and_floating_point_env.sysv">SysV</a>
|
||||
</h5>
|
||||
<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.rationale.x86_and_floating_point_env.f6" href="#ftn.context.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.rationale.x86_and_floating_point_env.f0" href="#context.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.rationale.x86_and_floating_point_env.f1" href="#context.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.rationale.x86_and_floating_point_env.f2" href="#context.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.rationale.x86_and_floating_point_env.f3" href="#context.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.rationale.x86_and_floating_point_env.f4" href="#context.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.rationale.x86_and_floating_point_env.f5" href="#context.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.rationale.x86_and_floating_point_env.f6" href="#context.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 © 2009 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>
|
||||
104
doc/html/context/reference.html
Normal file
104
doc/html/context/reference.html
Normal file
@ -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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="rationale/x86_and_floating_point_env.html" title="x86 and floating-point env">
|
||||
<link rel="next" href="todo.html" title="Todo">
|
||||
</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="../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="todo.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.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a>
|
||||
</h2></div></div></div>
|
||||
<h4>
|
||||
<a name="context.reference.h0"></a>
|
||||
<span><a name="context.reference.arm"></a></span><a class="link" href="reference.html#context.reference.arm">ARM</a>
|
||||
</h4>
|
||||
<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>
|
||||
<h4>
|
||||
<a name="context.reference.h1"></a>
|
||||
<span><a name="context.reference.mips"></a></span><a class="link" href="reference.html#context.reference.mips">MIPS</a>
|
||||
</h4>
|
||||
<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>
|
||||
<h4>
|
||||
<a name="context.reference.h2"></a>
|
||||
<span><a name="context.reference.powerpc32"></a></span><a class="link" href="reference.html#context.reference.powerpc32">PowerPC32</a>
|
||||
</h4>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE PowerPC Processor Supplement
|
||||
</li></ul></div>
|
||||
<h4>
|
||||
<a name="context.reference.h3"></a>
|
||||
<span><a name="context.reference.powerpc64"></a></span><a class="link" href="reference.html#context.reference.powerpc64">PowerPC64</a>
|
||||
</h4>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
SYSV ABI: PowerPC User Instruction Set Architecture, Book I
|
||||
</li></ul></div>
|
||||
<h4>
|
||||
<a name="context.reference.h4"></a>
|
||||
<span><a name="context.reference.x86_32"></a></span><a class="link" href="reference.html#context.reference.x86_32">X86-32</a>
|
||||
</h4>
|
||||
<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>
|
||||
<h4>
|
||||
<a name="context.reference.h5"></a>
|
||||
<span><a name="context.reference.x86_64"></a></span><a class="link" href="reference.html#context.reference.x86_64">X86-64</a>
|
||||
</h4>
|
||||
<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 © 2009 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="../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="todo.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
80
doc/html/context/requirements.html
Normal file
80
doc/html/context/requirements.html
Normal file
@ -0,0 +1,80 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Requirements</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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="overview.html" title="Overview">
|
||||
<link rel="next" href="context.html" title="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="overview.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.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.requirements"></a><a class="link" href="requirements.html" title="Requirements">Requirements</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
<span class="bold"><strong>Boost.Context</strong></span> must be built for the particular
|
||||
compiler(s) and CPU architecture(s)s being targeted. <span class="bold"><strong>Boost.Context</strong></span>
|
||||
includes assembly code and, therefore, requires GNU AS for supported POSIX
|
||||
systems, MASM for Windows/x86 systems and ARMasm for Windows/arm systems.
|
||||
</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>
|
||||
MASM64 (ml64.exe) is a part of Microsoft's Windows Driver Kit.
|
||||
</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>
|
||||
Please note that <code class="computeroutput"><span class="identifier">address</span><span class="special">-</span><span class="identifier">model</span><span class="special">=</span><span class="number">64</span></code> must be
|
||||
given to bjam command line on 64bit Windows for 64bit build; otherwise 32bit
|
||||
code will be generated.
|
||||
</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>
|
||||
For cross-compiling the lib you must specify certain additional properties
|
||||
at bjam command line: <code class="computeroutput"><span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span></code>, <code class="computeroutput"><span class="identifier">abi</span></code>, <code class="computeroutput"><span class="identifier">binary</span><span class="special">-</span><span class="identifier">format</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">architecture</span></code> and <code class="computeroutput"><span class="identifier">address</span><span class="special">-</span><span class="identifier">model</span></code>.
|
||||
</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 © 2009 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="overview.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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
79
doc/html/context/stack.html
Normal file
79
doc/html/context/stack.html
Normal file
@ -0,0 +1,79 @@
|
||||
<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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="context/boost_fcontext.html" title="Struct fcontext_t and related functions">
|
||||
<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="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="performance.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>
|
||||
<p>
|
||||
A <span class="emphasis"><em>fcontext_t</em></span> requires a stack which will be allocated/deallocated
|
||||
by a <span class="emphasis"><em>StackAllocator</em></span> (examples contain an implementation
|
||||
of <a href="../../../../../libs/context/example/simple_stack_allocator.hpp" target="_top">simple_stack_allocator</a>).
|
||||
</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 implementation of a <span class="emphasis"><em>StackAllocator</em></span> 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="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>make_fcontext()</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 <span class="emphasis"><em>StackAllocator</em></span> returns
|
||||
an address from the top of the stack (grows downwards) or the bottom of the
|
||||
stack (grows 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 © 2009 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/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="performance.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
51
doc/html/context/todo.html
Normal file
51
doc/html/context/todo.html
Normal file
@ -0,0 +1,51 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Todo</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="../index.html" title="Chapter 1. Context">
|
||||
<link rel="prev" href="reference.html" title="Reference">
|
||||
<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="reference.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="acknowledgements.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.todo"></a><a class="link" href="todo.html" title="Todo">Todo</a>
|
||||
</h2></div></div></div>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
provide support for SPARC, SuperH (SH4), S/390
|
||||
</li>
|
||||
<li class="listitem">
|
||||
support split-stack feature from gcc/gold linker
|
||||
</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 © 2009 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="../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="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
13
doc/html/context_HTML.manifest
Normal file
13
doc/html/context_HTML.manifest
Normal file
@ -0,0 +1,13 @@
|
||||
index.html
|
||||
context/overview.html
|
||||
context/requirements.html
|
||||
context/context.html
|
||||
context/context/boost_fcontext.html
|
||||
context/stack.html
|
||||
context/performance.html
|
||||
context/rationale.html
|
||||
context/rationale/other_apis_.html
|
||||
context/rationale/x86_and_floating_point_env.html
|
||||
context/reference.html
|
||||
context/todo.html
|
||||
context/acknowledgements.html
|
||||
64
doc/html/index.html
Normal file
64
doc/html/index.html
Normal file
@ -0,0 +1,64 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Chapter 1. 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="next" href="context/overview.html" title="Overview">
|
||||
</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="n" href="context/overview.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
<div class="chapter">
|
||||
<div class="titlepage"><div>
|
||||
<div><h2 class="title">
|
||||
<a name="context"></a>Chapter 1. Context</h2></div>
|
||||
<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><div class="legalnotice">
|
||||
<a name="context.legal"></a><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></div>
|
||||
</div></div>
|
||||
<div class="toc">
|
||||
<p><b>Table of Contents</b></p>
|
||||
<dl>
|
||||
<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">Struct <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/stack.html">Stack allocation</a></span></dt>
|
||||
<dt><span class="section"><a href="context/performance.html">Performance</a></span></dt>
|
||||
<dt><span class="section"><a href="context/rationale.html">Rationale</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="context/rationale/other_apis_.html">Other APIs </a></span></dt>
|
||||
<dt><span class="section"><a href="context/rationale/x86_and_floating_point_env.html">x86 and
|
||||
floating-point env</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="context/reference.html">Reference</a></span></dt>
|
||||
<dt><span class="section"><a href="context/todo.html">Todo</a></span></dt>
|
||||
<dt><span class="section"><a href="context/acknowledgements.html">Acknowledgments</a></span></dt>
|
||||
</dl>
|
||||
</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: January 16, 2014 at 17:01:39 GMT</small></p></td>
|
||||
<td align="right"><div class="copyright-footer"></div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="context/overview.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
</body>
|
||||
</html>
|
||||
@ -8,9 +8,10 @@
|
||||
[section:performance Performance]
|
||||
|
||||
Performance of __boost_context__ was measured on the platforms shown in the
|
||||
following table. Performance measurements were taken using `rdtsc`, with
|
||||
overhead corrections, on x86 platforms. In each case, stack protection was
|
||||
active, cache warm-up was accounted for, and the one running thread was pinned
|
||||
following table. Performance measurements were taken using `rdtsc` and
|
||||
`boost::chrono::high_resolution_clock`, 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'.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user