ceph/src/boost/libs/context/doc/html/context/context.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Struct fcontext_t</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Context">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Context">
   9 <link rel="prev" href="requirements.html" title="Requirements">
  10 <link rel="next" href="abstract_context.html" title="Context classes">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <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="abstract_context.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="context.context"></a><a class="link" href="context.html" title="Struct fcontext_t">Struct fcontext_t</a>
  28 </h2></div></div></div>
  29 <p>
  30       Each instance of <span class="emphasis"><em>fcontext_t</em></span> represents a context (CPU
  31       registers and stack space). Together with its related functions <span class="emphasis"><em>jump_fcontext()</em></span>
  32       and <span class="emphasis"><em>make_fcontext()</em></span> it provides a execution control transfer
  33       mechanism similar interface like <a href="http://www.kernel.org/doc/man-pages/online/pages/man2/getcontext.2.html" target="_top">ucontext_t</a>.
  34       <span class="emphasis"><em>fcontext_t</em></span> and its functions are located in <span class="emphasis"><em>boost::context</em></span>
  35       and the functions are declared as extern "C".
  36     </p>
  37 <div class="warning"><table border="0" summary="Warning">
  38 <tr>
  39 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
  40 <th align="left">Warning</th>
  41 </tr>
  42 <tr><td align="left" valign="top"><p>
  43         If <span class="emphasis"><em>fcontext_t</em></span> is used in a multi threaded application,
  44         it can migrated between threads, but must not reference <span class="emphasis"><em>thread-local
  45         storage</em></span>.
  46       </p></td></tr>
  47 </table></div>
  48 <div class="important"><table border="0" summary="Important">
  49 <tr>
  50 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
  51 <th align="left">Important</th>
  52 </tr>
  53 <tr><td align="left" valign="top"><p>
  54         The low level API is the part to port to new platforms.
  55       </p></td></tr>
  56 </table></div>
  57 <div class="note"><table border="0" summary="Note">
  58 <tr>
  59 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
  60 <th align="left">Note</th>
  61 </tr>
  62 <tr><td align="left" valign="top"><p>
  63         If <span class="emphasis"><em>fiber-local storage</em></span> is used on Windows, the user
  64         is responsible for calling <span class="emphasis"><em>::FlsAlloc()</em></span>, <span class="emphasis"><em>::FlsFree()</em></span>.
  65       </p></td></tr>
  66 </table></div>
  67 <h4>
  68 <a name="context.context.h0"></a>
  69       <span><a name="context.context.executing_a_context"></a></span><a class="link" href="context.html#context.context.executing_a_context">Executing
  70       a context</a>
  71     </h4>
  72 <p>
  73       A new context supposed to execute a <span class="emphasis"><em>context-function</em></span> (returning
  74       void and accepting void * as argument) will be created on top of the stack
  75       (at 16 byte boundary) by function <span class="emphasis"><em>make_fcontext()</em></span>.
  76     </p>
  77 <pre class="programlisting"><span class="comment">// context-function</span>
  78 <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">intptr</span><span class="special">);</span>
  79
  80 <span class="comment">// creates a new stack</span>
  81 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span> <span class="special">=</span> <span class="number">8192</span><span class="special">;</span>
  82 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span>
  83
  84 <span class="comment">// context fc uses f() as context function</span>
  85 <span class="comment">// fcontext_t is placed on top of context stack</span>
  86 <span class="comment">// a pointer to fcontext_t is returned</span>
  87 <span class="identifier">fcontext_t</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>
  88 </pre>
  89 <p>
  90       Calling <span class="emphasis"><em>jump_fcontext()</em></span> invokes the <span class="emphasis"><em>context-function</em></span>
  91       in a newly created context complete with registers, flags, stack and instruction
  92       pointers. When control should be returned to the original calling context,
  93       call <span class="emphasis"><em>jump_fcontext()</em></span>. The current context information
  94       (registers, flags, and stack and instruction pointers) is saved and the original
  95       context information is restored. Calling <span class="emphasis"><em>jump_fcontext()</em></span>
  96       again resumes execution in the second context after saving the new state of
  97       the original context.
  98     </p>
  99 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">fcontext_t</span> <span class="identifier">fcm</span><span class="special">,</span><span class="identifier">fc1</span><span class="special">,</span><span class="identifier">fc2</span><span class="special">;</span>
 100
 101 <span class="keyword">void</span> <span class="identifier">f1</span><span class="special">(</span><span class="keyword">void</span> <span class="special">*)</span>
 102 <span class="special">{</span>
 103     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"f1: entered"</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 104     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"f1: call jump_fcontext( &amp; fc1, fc2, 0)"</span><span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 105     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&amp;</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>
 106     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"f1: return"</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 107     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&amp;</span><span class="identifier">fc1</span><span class="special">,</span><span class="identifier">fcm</span><span class="special">,</span><span class="number">0</span><span class="special">);</span>
 108 <span class="special">}</span>
 109
 110 <span class="keyword">void</span> <span class="identifier">f2</span><span class="special">(</span><span class="keyword">void</span> <span class="special">*)</span>
 111 <span class="special">{</span>
 112     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"f2: entered"</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 113     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"f2: call jump_fcontext( &amp; fc2, fc1, 0)"</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 114     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&amp;</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>
 115     <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">&amp;&amp;!</span><span class="string">"f2: never returns"</span><span class="special">);</span>
 116 <span class="special">}</span>
 117
 118 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">(</span><span class="number">8192</span><span class="special">);</span>
 119 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp1</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span>
 120 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp2</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span>
 121
 122 <span class="identifier">fc1</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">make_fcontext</span><span class="special">(</span><span class="identifier">sp1</span><span class="special">,</span><span class="identifier">size</span><span class="special">,</span><span class="identifier">f1</span><span class="special">);</span>
 123 <span class="identifier">fc2</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">make_fcontext</span><span class="special">(</span><span class="identifier">sp2</span><span class="special">,</span><span class="identifier">size</span><span class="special">,</span><span class="identifier">f2</span><span class="special">);</span>
 124
 125 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="string">"main: call jump_fcontext( &amp; fcm, fc1, 0)"</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 126 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&amp;</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>
 127
 128 <span class="identifier">output</span><span class="special">:</span>
 129     <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">&amp;</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>
 130     <span class="identifier">f1</span><span class="special">:</span> <span class="identifier">entered</span>
 131     <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">&amp;</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>
 132     <span class="identifier">f2</span><span class="special">:</span> <span class="identifier">entered</span>
 133     <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">&amp;</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>
 134     <span class="identifier">f1</span><span class="special">:</span> <span class="keyword">return</span>
 135 </pre>
 136 <p>
 137       First call of <span class="emphasis"><em>jump_fcontext()</em></span> enters the <span class="emphasis"><em>context-function</em></span>
 138       <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>
 139       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
 140       <code class="computeroutput"><span class="identifier">jump_fcontext</span><span class="special">()</span></code>
 141       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>)
 142       after context fc1 becomes complete (return from <code class="computeroutput"><span class="identifier">f1</span><span class="special">()</span></code>).
 143     </p>
 144 <div class="warning"><table border="0" summary="Warning">
 145 <tr>
 146 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
 147 <th align="left">Warning</th>
 148 </tr>
 149 <tr><td align="left" valign="top"><p>
 150         Calling <span class="emphasis"><em>jump_fcontext()</em></span> to the same context from inside
 151         the same context results in undefined behaviour.
 152       </p></td></tr>
 153 </table></div>
 154 <div class="important"><table border="0" summary="Important">
 155 <tr>
 156 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
 157 <th align="left">Important</th>
 158 </tr>
 159 <tr><td align="left" valign="top"><p>
 160         The size of the stack is required to be larger than the size of fcontext_t.
 161       </p></td></tr>
 162 </table></div>
 163 <div class="note"><table border="0" summary="Note">
 164 <tr>
 165 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 166 <th align="left">Note</th>
 167 </tr>
 168 <tr><td align="left" valign="top"><p>
 169         In contrast to threads, which are preemtive, <span class="emphasis"><em>fcontext_t</em></span>
 170         switches are cooperative (programmer controls when switch will happen). The
 171         kernel is not involved in the context switches.
 172       </p></td></tr>
 173 </table></div>
 174 <h4>
 175 <a name="context.context.h1"></a>
 176       <span><a name="context.context.transfer_of_data"></a></span><a class="link" href="context.html#context.context.transfer_of_data">Transfer
 177       of data</a>
 178     </h4>
 179 <p>
 180       The third argument passed to <span class="emphasis"><em>jump_fcontext()</em></span>, in one context,
 181       is passed as the first argument of the <span class="emphasis"><em>context-function</em></span>
 182       if the context is started for the first time. In all following invocations
 183       of <span class="emphasis"><em>jump_fcontext()</em></span> the void * passed to <span class="emphasis"><em>jump_fcontext()</em></span>,
 184       in one context, is returned by <span class="emphasis"><em>jump_fcontext()</em></span> in the
 185       other context.
 186     </p>
 187 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">fcontext_t</span> <span class="identifier">fcm</span><span class="special">,</span><span class="identifier">fc</span><span class="special">;</span>
 188
 189 <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">pair_t</span><span class="special">;</span>
 190
 191 <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">param</span><span class="special">)</span>
 192 <span class="special">{</span>
 193     <span class="identifier">pair_t</span><span class="special">*</span> <span class="identifier">p</span><span class="special">=(</span><span class="identifier">pair_t</span><span class="special">*)</span><span class="identifier">param</span><span class="special">;</span>
 194     <span class="identifier">p</span><span class="special">=(</span><span class="identifier">pair_t</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">jump_fcontext</span><span class="special">(&amp;</span><span class="identifier">fc</span><span class="special">,</span><span class="identifier">fcm</span><span class="special">,(</span><span class="keyword">void</span> <span class="special">*)(</span><span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">first</span><span class="special">+</span><span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">second</span><span class="special">));</span>
 195     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">jump_fcontext</span><span class="special">(&amp;</span><span class="identifier">fc</span><span class="special">,</span><span class="identifier">fcm</span><span class="special">,(</span><span class="keyword">void</span> <span class="special">*)(</span><span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">first</span><span class="special">+</span><span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">second</span><span class="special">));</span>
 196 <span class="special">}</span>
 197
 198 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">(</span><span class="number">8192</span><span class="special">);</span>
 199 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">(</span><span class="identifier">size</span><span class="special">));</span>
 200
 201 <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>
 202 <span class="identifier">fc</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">make_fcontext</span><span class="special">(</span><span class="identifier">sp</span><span class="special">,</span><span class="identifier">size</span><span class="special">,</span><span class="identifier">f</span><span class="special">);</span>
 203
 204 <span class="keyword">int</span> <span class="identifier">res</span><span class="special">=(</span><span class="keyword">int</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">jump_fcontext</span><span class="special">(&amp;</span><span class="identifier">fcm</span><span class="special">,</span><span class="identifier">fc</span><span class="special">,(</span><span class="keyword">void</span> <span class="special">*)&amp;</span><span class="identifier">p</span><span class="special">);</span>
 205 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">first</span><span class="special">&lt;&lt;</span><span class="string">" + "</span><span class="special">&lt;&lt;</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">second</span><span class="special">&lt;&lt;</span><span class="string">" == "</span><span class="special">&lt;&lt;</span><span class="identifier">res</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 206
 207 <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>
 208 <span class="identifier">res</span><span class="special">=(</span><span class="keyword">int</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">jump_fcontext</span><span class="special">(&amp;</span><span class="identifier">fcm</span><span class="special">,</span><span class="identifier">fc</span><span class="special">,(</span><span class="keyword">void</span> <span class="special">*)&amp;</span><span class="identifier">p</span><span class="special">);</span>
 209 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">&lt;&lt;</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">first</span><span class="special">&lt;&lt;</span><span class="string">" + "</span><span class="special">&lt;&lt;</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">second</span><span class="special">&lt;&lt;</span><span class="string">" == "</span><span class="special">&lt;&lt;</span><span class="identifier">res</span><span class="special">&lt;&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 210
 211 <span class="identifier">output</span><span class="special">:</span>
 212     <span class="number">2</span> <span class="special">+</span> <span class="number">7</span> <span class="special">==</span> <span class="number">9</span>
 213     <span class="number">5</span> <span class="special">+</span> <span class="number">6</span> <span class="special">==</span> <span class="number">11</span>
 214 </pre>
 215 <h4>
 216 <a name="context.context.h2"></a>
 217       <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
 218       in <span class="emphasis"><em>context-function</em></span></a>
 219     </h4>
 220 <p>
 221       If the <span class="emphasis"><em>context-function</em></span> emits an exception, the behaviour
 222       is undefined.
 223     </p>
 224 <div class="important"><table border="0" summary="Important">
 225 <tr>
 226 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
 227 <th align="left">Important</th>
 228 </tr>
 229 <tr><td align="left" valign="top"><p>
 230         <span class="emphasis"><em>context-function</em></span> should wrap the code in a try/catch
 231         block.
 232       </p></td></tr>
 233 </table></div>
 234 <div class="important"><table border="0" summary="Important">
 235 <tr>
 236 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
 237 <th align="left">Important</th>
 238 </tr>
 239 <tr><td align="left" valign="top"><p>
 240         Do not jump from inside a catch block and then re-throw the exception in
 241         another execution context.
 242       </p></td></tr>
 243 </table></div>
 244 <h4>
 245 <a name="context.context.h3"></a>
 246       <span><a name="context.context.stack_unwinding"></a></span><a class="link" href="context.html#context.context.stack_unwinding">Stack
 247       unwinding</a>
 248     </h4>
 249 <p>
 250       Sometimes it is necessary to unwind the stack of an unfinished context to destroy
 251       local stack variables so they can release allocated resources (RAII pattern).
 252       The user is responsible for this task.
 253     </p>
 254 <h4>
 255 <a name="context.context.h4"></a>
 256       <span><a name="context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fcontext_t__phrase___code__and_related_functions"><code class="computeroutput"><span class="identifier">fcontext_t</span></code> and related functions</a>
 257     </h4>
 258 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">stack_t</span>
 259 <span class="special">{</span>
 260     <span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp</span><span class="special">;</span>
 261     <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">;</span>
 262 <span class="special">};</span>
 263
 264 <span class="keyword">typedef</span> <span class="special">&lt;</span><span class="identifier">opaque</span> <span class="identifier">pointer</span> <span class="special">&gt;</span> <span class="identifier">fcontext_t</span><span class="special">;</span>
 265
 266 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">vp</span><span class="special">);</span>
 267 <span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">sp</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span><span class="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="keyword">void</span> <span class="special">*));</span>
 268 </pre>
 269 <h4>
 270 <a name="context.context.h5"></a>
 271       <span><a name="context.context._code__phrase_role__identifier__sp__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__sp__phrase___code_"><code class="computeroutput"><span class="identifier">sp</span></code></a>
 272     </h4>
 273 <div class="variablelist">
 274 <p class="title"><b></b></p>
 275 <dl>
 276 <dt><span class="term">Member:</span></dt>
 277 <dd><p>
 278             Pointer to the beginning of the stack (depending of the architecture
 279             the stack grows downwards or upwards).
 280           </p></dd>
 281 </dl>
 282 </div>
 283 <h4>
 284 <a name="context.context.h6"></a>
 285       <span><a name="context.context._code__phrase_role__identifier__size__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__size__phrase___code_"><code class="computeroutput"><span class="identifier">size</span></code></a>
 286     </h4>
 287 <div class="variablelist">
 288 <p class="title"><b></b></p>
 289 <dl>
 290 <dt><span class="term">Member:</span></dt>
 291 <dd><p>
 292             Size of the stack in bytes.
 293           </p></dd>
 294 </dl>
 295 </div>
 296 <h4>
 297 <a name="context.context.h7"></a>
 298       <span><a name="context.context._code__phrase_role__identifier__fc_stack__phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fc_stack__phrase___code_"><code class="computeroutput"><span class="identifier">fc_stack</span></code></a>
 299     </h4>
 300 <div class="variablelist">
 301 <p class="title"><b></b></p>
 302 <dl>
 303 <dt><span class="term">Member:</span></dt>
 304 <dd><p>
 305             Tracks the memory for the context's stack.
 306           </p></dd>
 307 </dl>
 308 </div>
 309 <h4>
 310 <a name="context.context.h8"></a>
 311       <span><a name="context.context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__jump_fcontext__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase__phrase_role__special_____phrase___phrase_role__identifier__ofc__phrase__phrase_role__special_____phrase__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__nfc__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase___phrase_role__special_____phrase___phrase_role__identifier__p__phrase__phrase_role__special_____phrase___code_"><code class="computeroutput"><span class="keyword">void</span> <span class="special">*</span> <span class="identifier">jump_fcontext</span><span class="special">(</span><span class="identifier">fcontext_t</span><span class="special">*</span> <span class="identifier">ofc</span><span class="special">,</span><span class="identifier">fcontext_t</span> <span class="identifier">nfc</span><span class="special">,</span><span class="keyword">void</span> <span class="special">*</span>
 312       <span class="identifier">p</span><span class="special">)</span></code></a>
 313     </h4>
 314 <div class="variablelist">
 315 <p class="title"><b></b></p>
 316 <dl>
 317 <dt><span class="term">Effects:</span></dt>
 318 <dd><p>
 319             Stores the current context data (stack pointer, instruction pointer,
 320             and CPU registers) to <code class="computeroutput"><span class="special">*</span><span class="identifier">ofc</span></code> and restores the context data from
 321             <code class="computeroutput"><span class="identifier">nfc</span></code>, which implies jumping
 322             to execution context <code class="computeroutput"><span class="identifier">nfc</span></code>.
 323             The void * argument, <code class="computeroutput"><span class="identifier">p</span></code>,
 324             is passed to the current context to be returned by the most recent call
 325             to <code class="computeroutput"><span class="identifier">jump_fcontext</span><span class="special">()</span></code>
 326             in the same thread.
 327           </p></dd>
 328 <dt><span class="term">Returns:</span></dt>
 329 <dd><p>
 330             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>,
 331             if any.
 332           </p></dd>
 333 </dl>
 334 </div>
 335 <h4>
 336 <a name="context.context.h9"></a>
 337       <span><a name="context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__keyword__void__phrase___phrase_role__special_______phrase___code_"></a></span><a class="link" href="context.html#context.context._code__phrase_role__identifier__fcontext_t__phrase___phrase_role__identifier__make_fcontext__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special_____phrase___phrase_role__identifier__sp__phrase__phrase_role__special_____phrase__phrase_role__identifier__std__phrase__phrase_role__special______phrase__phrase_role__identifier__size_t__phrase___phrase_role__identifier__size__phrase__phrase_role__special_____phrase__phrase_role__keyword__void__phrase__phrase_role__special______phrase__phrase_role__identifier__fn__phrase__phrase_role__special______phrase__phrase_role__keyword__void__phrase___phrase_role__special_______phrase___code_"><code class="computeroutput"><span class="identifier">fcontext_t</span> <span class="identifier">make_fcontext</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span>
 338       <span class="identifier">sp</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span>
 339       <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="keyword">void</span> <span class="special">*))</span></code></a>
 340     </h4>
 341 <div class="variablelist">
 342 <p class="title"><b></b></p>
 343 <dl>
 344 <dt><span class="term">Precondition:</span></dt>
 345 <dd><p>
 346             Stack <code class="computeroutput"><span class="identifier">sp</span></code> and function
 347             pointer <code class="computeroutput"><span class="identifier">fn</span></code> are valid
 348             (depending on the architecture <code class="computeroutput"><span class="identifier">sp</span></code>
 349             points to the top or bottom of the stack) and <code class="computeroutput"><span class="identifier">size</span></code>
 350             &gt; 0.
 351           </p></dd>
 352 <dt><span class="term">Effects:</span></dt>
 353 <dd><p>
 354             Creates an fcontext_t on top of the stack and prepares the stack to execute
 355             the <span class="emphasis"><em>context-function</em></span> <code class="computeroutput"><span class="identifier">fn</span></code>.
 356           </p></dd>
 357 <dt><span class="term">Returns:</span></dt>
 358 <dd><p>
 359             Returns a fcontext_t which is placed on the stack.
 360           </p></dd>
 361 </dl>
 362 </div>
 363 </div>
 364 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 365 <td align="left"></td>
 366 <td align="right"><div class="copyright-footer">Copyright &#169; 2014 Oliver Kowalke<p>
 367         Distributed under the Boost Software License, Version 1.0. (See accompanying
 368         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>)
 369       </p>
 370 </div></td>
 371 </tr></table>
 372 <hr>
 373 <div class="spirit-nav">
 374 <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="abstract_context.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 375 </div>
 376 </body>
 377 </html>