ceph/src/boost/libs/fiber/doc/html/fiber/custom.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Customization</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;Fiber">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
   9 <link rel="prev" href="performance.html" title="Performance">
  10 <link rel="next" href="rationale.html" title="Rationale">
  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="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.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="fiber.custom"></a><a name="custom"></a><a class="link" href="custom.html" title="Customization">Customization</a>
  28 </h2></div></div></div>
  29 <h4>
  30 <a name="fiber.custom.h0"></a>
  31       <span><a name="fiber.custom.overview"></a></span><a class="link" href="custom.html#fiber.custom.overview">Overview</a>
  32     </h4>
  33 <p>
  34       As noted in the <a class="link" href="scheduling.html#scheduling">Scheduling</a> section, by default
  35       <span class="bold"><strong>Boost.Fiber</strong></span> uses its own <a class="link" href="scheduling.html#class_round_robin"><code class="computeroutput">round_robin</code></a> scheduler
  36       for each thread. To control the way <span class="bold"><strong>Boost.Fiber</strong></span>
  37       schedules ready fibers on a particular thread, in general you must follow several
  38       steps. This section discusses those steps, whereas <a class="link" href="scheduling.html#scheduling">Scheduling</a>
  39       serves as a reference for the classes involved.
  40     </p>
  41 <p>
  42       The library's fiber manager keeps track of suspended (blocked) fibers. Only
  43       when a fiber becomes ready to run is it passed to the scheduler. Of course,
  44       if there are fewer than two ready fibers, the scheduler's job is trivial. Only
  45       when there are two or more ready fibers does the particular scheduler implementation
  46       start to influence the overall sequence of fiber execution.
  47     </p>
  48 <p>
  49       In this section we illustrate a simple custom scheduler that honors an integer
  50       fiber priority. We will implement it such that a fiber with higher priority
  51       is preferred over a fiber with lower priority. Any fibers with equal priority
  52       values are serviced on a round-robin basis.
  53     </p>
  54 <p>
  55       The full source code for the examples below is found in <a href="../../../examples/priority.cpp" target="_top">priority.cpp</a>.
  56     </p>
  57 <h4>
  58 <a name="fiber.custom.h1"></a>
  59       <span><a name="fiber.custom.custom_property_class"></a></span><a class="link" href="custom.html#fiber.custom.custom_property_class">Custom
  60       Property Class</a>
  61     </h4>
  62 <p>
  63       The first essential point is that we must associate an integer priority with
  64       each fiber.<sup>[<a name="fiber.custom.f0" href="#ftn.fiber.custom.f0" class="footnote">9</a>]</sup>
  65     </p>
  66 <p>
  67       One might suggest deriving a custom <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> subclass to store such
  68       properties. There are a couple of reasons for the present mechanism.
  69     </p>
  70 <div class="orderedlist"><ol class="orderedlist" type="1">
  71 <li class="listitem">
  72           <span class="bold"><strong>Boost.Fiber</strong></span> provides a number of different
  73           ways to launch a fiber. (Consider <a class="link" href="synchronization/futures/future.html#fibers_async"><code class="computeroutput">fibers::async()</code></a>.) Higher-level
  74           libraries might introduce additional such wrapper functions. A custom scheduler
  75           must associate its custom properties with <span class="emphasis"><em>every</em></span> fiber
  76           in the thread, not only the ones explicitly launched by instantiating a
  77           custom <code class="computeroutput"><span class="identifier">fiber</span></code> subclass.
  78         </li>
  79 <li class="listitem">
  80           Consider a large existing program that launches fibers in many different
  81           places in the code. We discover a need to introduce a custom scheduler
  82           for a particular thread. If supporting that scheduler's custom properties
  83           required a particular <code class="computeroutput"><span class="identifier">fiber</span></code>
  84           subclass, we would have to hunt down and modify every place that launches
  85           a fiber on that thread.
  86         </li>
  87 <li class="listitem">
  88           The <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> class is actually just a handle to internal <a class="link" href="scheduling.html#class_context"><code class="computeroutput">context</code></a> data.
  89           A subclass of <code class="computeroutput"><span class="identifier">fiber</span></code> would
  90           not add data to <code class="computeroutput"><span class="identifier">context</span></code>.
  91         </li>
  92 </ol></div>
  93 <p>
  94       The present mechanism allows you to <span class="quote">&#8220;<span class="quote">drop in</span>&#8221;</span> a custom scheduler
  95       with its attendant custom properties <span class="emphasis"><em>without</em></span> altering
  96       the rest of your application.
  97     </p>
  98 <p>
  99       Instead of deriving a custom scheduler fiber properties subclass from <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a>,
 100       you must instead derive it from <a class="link" href="scheduling.html#class_fiber_properties"><code class="computeroutput">fiber_properties</code></a>.
 101     </p>
 102 <p>
 103 </p>
 104 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">priority_props</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber_properties</span> <span class="special">{</span>
 105 <span class="keyword">public</span><span class="special">:</span>
 106     <span class="identifier">priority_props</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">context</span> <span class="special">*</span> <span class="identifier">ctx</span><span class="special">):</span>
 107         <span class="identifier">fiber_properties</span><span class="special">(</span> <span class="identifier">ctx</span><span class="special">),</span> <a class="co" name="fiber.custom.c0" href="custom.html#fiber.custom.c1"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
 108         <span class="identifier">priority_</span><span class="special">(</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
 109     <span class="special">}</span>
 110
 111     <span class="keyword">int</span> <span class="identifier">get_priority</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span>
 112         <span class="keyword">return</span> <span class="identifier">priority_</span><span class="special">;</span> <a class="co" name="fiber.custom.c2" href="custom.html#fiber.custom.c3"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
 113     <span class="special">}</span>
 114
 115     <span class="comment">// Call this method to alter priority, because we must notify</span>
 116     <span class="comment">// priority_scheduler of any change.</span>
 117     <span class="keyword">void</span> <span class="identifier">set_priority</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">{</span> <a class="co" name="fiber.custom.c4" href="custom.html#fiber.custom.c5"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
 118         <span class="comment">// Of course, it's only worth reshuffling the queue and all if we're</span>
 119         <span class="comment">// actually changing the priority.</span>
 120         <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">p</span> <span class="special">!=</span> <span class="identifier">priority_</span><span class="special">)</span> <span class="special">{</span>
 121             <span class="identifier">priority_</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">;</span>
 122             <span class="identifier">notify</span><span class="special">();</span>
 123         <span class="special">}</span>
 124     <span class="special">}</span>
 125
 126     <span class="comment">// The fiber name of course is solely for purposes of this example</span>
 127     <span class="comment">// program; it has nothing to do with implementing scheduler priority.</span>
 128     <span class="comment">// This is a public data member -- not requiring set/get access methods --</span>
 129     <span class="comment">// because we need not inform the scheduler of any change.</span>
 130     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">name</span><span class="special">;</span> <a class="co" name="fiber.custom.c6" href="custom.html#fiber.custom.c7"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a>
 131 <span class="keyword">private</span><span class="special">:</span>
 132     <span class="keyword">int</span> <span class="identifier">priority_</span><span class="special">;</span>
 133 <span class="special">};</span>
 134 </pre>
 135 <p>
 136     </p>
 137 <div class="calloutlist"><table border="0" summary="Callout list">
 138 <tr>
 139 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c1"></a><a href="#fiber.custom.c0"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 140 <td valign="top" align="left"><p>
 141           Your subclass constructor must accept a <code class="literal"><a class="link" href="scheduling.html#class_context"><code class="computeroutput">context</code></a>*</code>
 142           and pass it to the <code class="computeroutput"><span class="identifier">fiber_properties</span></code>
 143           constructor.
 144         </p></td>
 145 </tr>
 146 <tr>
 147 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c3"></a><a href="#fiber.custom.c2"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
 148 <td valign="top" align="left"><p>
 149           Provide read access methods at your own discretion.
 150         </p></td>
 151 </tr>
 152 <tr>
 153 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c5"></a><a href="#fiber.custom.c4"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
 154 <td valign="top" align="left"><p>
 155           It's important to call <code class="computeroutput"><span class="identifier">notify</span><span class="special">()</span></code> on any change in a property that can
 156           affect the scheduler's behavior. Therefore, such modifications should only
 157           be performed through an access method.
 158         </p></td>
 159 </tr>
 160 <tr>
 161 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c7"></a><a href="#fiber.custom.c6"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
 162 <td valign="top" align="left"><p>
 163           A property that does not affect the scheduler does not need access methods.
 164         </p></td>
 165 </tr>
 166 </table></div>
 167 <h4>
 168 <a name="fiber.custom.h2"></a>
 169       <span><a name="fiber.custom.custom_scheduler_class"></a></span><a class="link" href="custom.html#fiber.custom.custom_scheduler_class">Custom
 170       Scheduler Class</a>
 171     </h4>
 172 <p>
 173       Now we can derive a custom scheduler from <a class="link" href="scheduling.html#class_algorithm_with_properties"><code class="computeroutput">algorithm_with_properties&lt;&gt;</code></a>,
 174       specifying our custom property class <code class="computeroutput"><span class="identifier">priority_props</span></code>
 175       as the template parameter.
 176     </p>
 177 <p>
 178 </p>
 179 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">priority_scheduler</span> <span class="special">:</span>
 180     <span class="keyword">public</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">algo</span><span class="special">::</span><span class="identifier">algorithm_with_properties</span><span class="special">&lt;</span> <span class="identifier">priority_props</span> <span class="special">&gt;</span> <span class="special">{</span>
 181 <span class="keyword">private</span><span class="special">:</span>
 182     <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">scheduler</span><span class="special">::</span><span class="identifier">ready_queue_t</span><a class="co" name="fiber.custom.c8" href="custom.html#fiber.custom.c9"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>   <span class="identifier">rqueue_t</span><span class="special">;</span>
 183
 184     <span class="identifier">rqueue_t</span>                                <span class="identifier">rqueue_</span><span class="special">;</span>
 185     <span class="identifier">std</span><span class="special">::</span><span class="identifier">mutex</span>                  <span class="identifier">mtx_</span><span class="special">{};</span>
 186     <span class="identifier">std</span><span class="special">::</span><span class="identifier">condition_variable</span>     <span class="identifier">cnd_</span><span class="special">{};</span>
 187     <span class="keyword">bool</span>                        <span class="identifier">flag_</span><span class="special">{</span> <span class="keyword">false</span> <span class="special">};</span>
 188
 189 <span class="keyword">public</span><span class="special">:</span>
 190     <span class="identifier">priority_scheduler</span><span class="special">()</span> <span class="special">:</span>
 191         <span class="identifier">rqueue_</span><span class="special">()</span> <span class="special">{</span>
 192     <span class="special">}</span>
 193
 194     <span class="comment">// For a subclass of algorithm_with_properties&lt;&gt;, it's important to</span>
 195     <span class="comment">// override the correct awakened() overload.</span>
 196     <a class="co" name="fiber.custom.c10" href="custom.html#fiber.custom.c11"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">awakened</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</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">priority_props</span> <span class="special">&amp;</span> <span class="identifier">props</span><span class="special">)</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 197         <span class="keyword">int</span> <span class="identifier">ctx_priority</span> <span class="special">=</span> <span class="identifier">props</span><span class="special">.</span><span class="identifier">get_priority</span><span class="special">();</span> <a class="co" name="fiber.custom.c12" href="custom.html#fiber.custom.c13"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
 198         <span class="comment">// With this scheduler, fibers with higher priority values are</span>
 199         <span class="comment">// preferred over fibers with lower priority values. But fibers with</span>
 200         <span class="comment">// equal priority values are processed in round-robin fashion. So when</span>
 201         <span class="comment">// we're handed a new context*, put it at the end of the fibers</span>
 202         <span class="comment">// with that same priority. In other words: search for the first fiber</span>
 203         <span class="comment">// in the queue with LOWER priority, and insert before that one.</span>
 204         <span class="identifier">rqueue_t</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">i</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span><span class="special">(</span> <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span>
 205             <span class="special">[</span><span class="identifier">ctx_priority</span><span class="special">,</span><span class="keyword">this</span><span class="special">](</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">context</span> <span class="special">&amp;</span> <span class="identifier">c</span><span class="special">)</span>
 206             <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">properties</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">c</span> <span class="special">).</span><span class="identifier">get_priority</span><span class="special">()</span> <span class="special">&lt;</span> <span class="identifier">ctx_priority</span><span class="special">;</span> <span class="special">}));</span>
 207         <span class="comment">// Now, whether or not we found a fiber with lower priority,</span>
 208         <span class="comment">// insert this new fiber here.</span>
 209         <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">i</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">ctx</span><span class="special">);</span>
 210     <span class="special">}</span>
 211
 212     <a class="co" name="fiber.custom.c14" href="custom.html#fiber.custom.c15"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a><span class="keyword">virtual</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">context</span> <span class="special">*</span> <span class="identifier">pick_next</span><span class="special">()</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 213         <span class="comment">// if ready queue is empty, just tell caller</span>
 214         <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()</span> <span class="special">)</span> <span class="special">{</span>
 215             <span class="keyword">return</span> <span class="keyword">nullptr</span><span class="special">;</span>
 216         <span class="special">}</span>
 217         <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</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="special">&amp;</span> <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">front</span><span class="special">()</span> <span class="special">);</span>
 218         <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">pop_front</span><span class="special">();</span>
 219         <span class="keyword">return</span> <span class="identifier">ctx</span><span class="special">;</span>
 220     <span class="special">}</span>
 221
 222     <a class="co" name="fiber.custom.c16" href="custom.html#fiber.custom.c17"><img src="../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a><span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">has_ready_fibers</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 223         <span class="keyword">return</span> <span class="special">!</span> <span class="identifier">rqueue_</span><span class="special">.</span><span class="identifier">empty</span><span class="special">();</span>
 224     <span class="special">}</span>
 225
 226     <a class="co" name="fiber.custom.c18" href="custom.html#fiber.custom.c19"><img src="../../../../../doc/src/images/callouts/6.png" alt="6" border="0"></a><span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">property_change</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</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">priority_props</span> <span class="special">&amp;</span> <span class="identifier">props</span><span class="special">)</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 227         <span class="comment">// Although our priority_props class defines multiple properties, only</span>
 228         <span class="comment">// one of them (priority) actually calls notify() when changed. The</span>
 229         <span class="comment">// point of a property_change() override is to reshuffle the ready</span>
 230         <span class="comment">// queue according to the updated priority value.</span>
 231
 232         <span class="comment">// 'ctx' might not be in our queue at all, if caller is changing the</span>
 233         <span class="comment">// priority of (say) the running fiber. If it's not there, no need to</span>
 234         <span class="comment">// move it: we'll handle it next time it hits awakened().</span>
 235         <span class="keyword">if</span> <span class="special">(</span> <span class="special">!</span> <span class="identifier">ctx</span><span class="special">-&gt;</span><span class="identifier">ready_is_linked</span><span class="special">())</span> <span class="special">{</span> <a class="co" name="fiber.custom.c20" href="custom.html#fiber.custom.c21"><img src="../../../../../doc/src/images/callouts/7.png" alt="7" border="0"></a>
 236             <span class="keyword">return</span><span class="special">;</span>
 237         <span class="special">}</span>
 238
 239         <span class="comment">// Found ctx: unlink it</span>
 240         <span class="identifier">ctx</span><span class="special">-&gt;</span><span class="identifier">ready_unlink</span><span class="special">();</span>
 241
 242         <span class="comment">// Here we know that ctx was in our ready queue, but we've unlinked</span>
 243         <span class="comment">// it. We happen to have a method that will (re-)add a context* to the</span>
 244         <span class="comment">// right place in the ready queue.</span>
 245         <span class="identifier">awakened</span><span class="special">(</span> <span class="identifier">ctx</span><span class="special">,</span> <span class="identifier">props</span><span class="special">);</span>
 246     <span class="special">}</span>
 247
 248     <span class="keyword">void</span> <span class="identifier">suspend_until</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">steady_clock</span><span class="special">::</span><span class="identifier">time_point</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">time_point</span><span class="special">)</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 249         <span class="keyword">if</span> <span class="special">(</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">steady_clock</span><span class="special">::</span><span class="identifier">time_point</span><span class="special">::</span><span class="identifier">max</span><span class="special">)()</span> <span class="special">==</span> <span class="identifier">time_point</span><span class="special">)</span> <span class="special">{</span>
 250             <span class="identifier">std</span><span class="special">::</span><span class="identifier">unique_lock</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">mutex</span> <span class="special">&gt;</span> <span class="identifier">lk</span><span class="special">(</span> <span class="identifier">mtx_</span><span class="special">);</span>
 251             <span class="identifier">cnd_</span><span class="special">.</span><span class="identifier">wait</span><span class="special">(</span> <span class="identifier">lk</span><span class="special">,</span> <span class="special">[</span><span class="keyword">this</span><span class="special">](){</span> <span class="keyword">return</span> <span class="identifier">flag_</span><span class="special">;</span> <span class="special">});</span>
 252             <span class="identifier">flag_</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
 253         <span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
 254             <span class="identifier">std</span><span class="special">::</span><span class="identifier">unique_lock</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">mutex</span> <span class="special">&gt;</span> <span class="identifier">lk</span><span class="special">(</span> <span class="identifier">mtx_</span><span class="special">);</span>
 255             <span class="identifier">cnd_</span><span class="special">.</span><span class="identifier">wait_until</span><span class="special">(</span> <span class="identifier">lk</span><span class="special">,</span> <span class="identifier">time_point</span><span class="special">,</span> <span class="special">[</span><span class="keyword">this</span><span class="special">](){</span> <span class="keyword">return</span> <span class="identifier">flag_</span><span class="special">;</span> <span class="special">});</span>
 256             <span class="identifier">flag_</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
 257         <span class="special">}</span>
 258     <span class="special">}</span>
 259
 260     <span class="keyword">void</span> <span class="identifier">notify</span><span class="special">()</span> <span class="keyword">noexcept</span> <span class="special">{</span>
 261         <span class="identifier">std</span><span class="special">::</span><span class="identifier">unique_lock</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">mutex</span> <span class="special">&gt;</span> <span class="identifier">lk</span><span class="special">(</span> <span class="identifier">mtx_</span><span class="special">);</span>
 262         <span class="identifier">flag_</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
 263         <span class="identifier">lk</span><span class="special">.</span><span class="identifier">unlock</span><span class="special">();</span>
 264         <span class="identifier">cnd_</span><span class="special">.</span><span class="identifier">notify_all</span><span class="special">();</span>
 265     <span class="special">}</span>
 266 <span class="special">};</span>
 267 </pre>
 268 <p>
 269     </p>
 270 <div class="calloutlist"><table border="0" summary="Callout list">
 271 <tr>
 272 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c9"></a><a href="#fiber.custom.c8"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 273 <td valign="top" align="left"><p>
 274           See <a class="link" href="scheduling.html#ready_queue_t">ready_queue_t</a>.
 275         </p></td>
 276 </tr>
 277 <tr>
 278 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c11"></a><a href="#fiber.custom.c10"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
 279 <td valign="top" align="left"><p>
 280           You must override the <a class="link" href="scheduling.html#algorithm_with_properties_awakened"><code class="computeroutput">algorithm_with_properties::awakened()</code></a>
 281          method.
 282           This is how your scheduler receives notification of a fiber that has become
 283           ready to run.
 284         </p></td>
 285 </tr>
 286 <tr>
 287 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c13"></a><a href="#fiber.custom.c12"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
 288 <td valign="top" align="left"><p>
 289           <code class="computeroutput"><span class="identifier">props</span></code> is the instance of
 290           priority_props associated with the passed fiber <code class="computeroutput"><span class="identifier">ctx</span></code>.
 291         </p></td>
 292 </tr>
 293 <tr>
 294 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c15"></a><a href="#fiber.custom.c14"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
 295 <td valign="top" align="left"><p>
 296           You must override the <a class="link" href="scheduling.html#algorithm_with_properties_pick_next"><code class="computeroutput">algorithm_with_properties::pick_next()</code></a>
 297          method.
 298           This is how your scheduler actually advises the fiber manager of the next
 299           fiber to run.
 300         </p></td>
 301 </tr>
 302 <tr>
 303 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c17"></a><a href="#fiber.custom.c16"><img src="../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a> </p></td>
 304 <td valign="top" align="left"><p>
 305           You must override <a class="link" href="scheduling.html#algorithm_with_properties_has_ready_fibers"><code class="computeroutput">algorithm_with_properties::has_ready_fibers()</code></a>
 306       to
 307           inform the fiber manager of the state of your ready queue.
 308         </p></td>
 309 </tr>
 310 <tr>
 311 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c19"></a><a href="#fiber.custom.c18"><img src="../../../../../doc/src/images/callouts/6.png" alt="6" border="0"></a> </p></td>
 312 <td valign="top" align="left"><p>
 313           Overriding <a class="link" href="scheduling.html#algorithm_with_properties_property_change"><code class="computeroutput">algorithm_with_properties::property_change()</code></a>
 314          is
 315           optional. This override handles the case in which the running fiber changes
 316           the priority of another ready fiber: a fiber already in our queue. In that
 317           case, move the updated fiber within the queue.
 318         </p></td>
 319 </tr>
 320 <tr>
 321 <td width="5%" valign="top" align="left"><p><a name="fiber.custom.c21"></a><a href="#fiber.custom.c20"><img src="../../../../../doc/src/images/callouts/7.png" alt="7" border="0"></a> </p></td>
 322 <td valign="top" align="left"><p>
 323           Your <code class="computeroutput"><span class="identifier">property_change</span><span class="special">()</span></code>
 324           override must be able to handle the case in which the passed <code class="computeroutput"><span class="identifier">ctx</span></code> is not in your ready queue. It might
 325           be running, or it might be blocked.
 326         </p></td>
 327 </tr>
 328 </table></div>
 329 <p>
 330       Our example <code class="computeroutput"><span class="identifier">priority_scheduler</span></code>
 331       doesn't override <a class="link" href="scheduling.html#algorithm_with_properties_new_properties"><code class="computeroutput">algorithm_with_properties::new_properties()</code></a>:
 332       we're content with allocating <code class="computeroutput"><span class="identifier">priority_props</span></code>
 333       instances on the heap.
 334     </p>
 335 <h4>
 336 <a name="fiber.custom.h3"></a>
 337       <span><a name="fiber.custom.replace_default_scheduler"></a></span><a class="link" href="custom.html#fiber.custom.replace_default_scheduler">Replace
 338       Default Scheduler</a>
 339     </h4>
 340 <p>
 341       You must call <a class="link" href="fiber_mgmt/fiber.html#use_scheduling_algorithm"><code class="computeroutput">use_scheduling_algorithm()</code></a> at the start
 342       of each thread on which you want <span class="bold"><strong>Boost.Fiber</strong></span>
 343       to use your custom scheduler rather than its own default <a class="link" href="scheduling.html#class_round_robin"><code class="computeroutput">round_robin</code></a>.
 344       Specifically, you must call <code class="computeroutput"><span class="identifier">use_scheduling_algorithm</span><span class="special">()</span></code> before performing any other <span class="bold"><strong>Boost.Fiber</strong></span>
 345       operations on that thread.
 346     </p>
 347 <p>
 348 </p>
 349 <pre class="programlisting"><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>
 350     <span class="comment">// make sure we use our priority_scheduler rather than default round_robin</span>
 351     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">use_scheduling_algorithm</span><span class="special">&lt;</span> <span class="identifier">priority_scheduler</span> <span class="special">&gt;();</span>
 352     <span class="special">...</span>
 353 <span class="special">}</span>
 354 </pre>
 355 <p>
 356     </p>
 357 <h4>
 358 <a name="fiber.custom.h4"></a>
 359       <span><a name="fiber.custom.use_properties"></a></span><a class="link" href="custom.html#fiber.custom.use_properties">Use
 360       Properties</a>
 361     </h4>
 362 <p>
 363       The running fiber can access its own <a class="link" href="scheduling.html#class_fiber_properties"><code class="computeroutput">fiber_properties</code></a> subclass
 364       instance by calling <a class="link" href="fiber_mgmt/this_fiber.html#this_fiber_properties"><code class="computeroutput">this_fiber::properties()</code></a>. Although
 365       <code class="computeroutput"><span class="identifier">properties</span><span class="special">&lt;&gt;()</span></code>
 366       is a nullary function, you must pass, as a template parameter, the <code class="computeroutput"><span class="identifier">fiber_properties</span></code> subclass.
 367     </p>
 368 <p>
 369 </p>
 370 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">this_fiber</span><span class="special">::</span><span class="identifier">properties</span><span class="special">&lt;</span> <span class="identifier">priority_props</span> <span class="special">&gt;().</span><span class="identifier">name</span> <span class="special">=</span> <span class="string">"main"</span><span class="special">;</span>
 371 </pre>
 372 <p>
 373     </p>
 374 <p>
 375       Given a <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> instance still connected with a running fiber (that
 376       is, not <a class="link" href="fiber_mgmt/fiber.html#fiber_detach"><code class="computeroutput">fiber::detach()</code></a>ed), you may access that fiber's properties
 377       using <a class="link" href="fiber_mgmt/fiber.html#fiber_properties"><code class="computeroutput">fiber::properties()</code></a>. As with <code class="computeroutput"><span class="identifier">this_fiber</span><span class="special">::</span><span class="identifier">properties</span><span class="special">&lt;&gt;()</span></code>, you must pass your <code class="computeroutput"><span class="identifier">fiber_properties</span></code> subclass as the template
 378       parameter.
 379     </p>
 380 <p>
 381 </p>
 382 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">&gt;</span>
 383 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">launch</span><span class="special">(</span> <span class="identifier">Fn</span> <span class="special">&amp;&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">priority</span><span class="special">)</span> <span class="special">{</span>
 384     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">fiber</span><span class="special">(</span> <span class="identifier">func</span><span class="special">);</span>
 385     <span class="identifier">priority_props</span> <span class="special">&amp;</span> <span class="identifier">props</span><span class="special">(</span> <span class="identifier">fiber</span><span class="special">.</span><span class="identifier">properties</span><span class="special">&lt;</span> <span class="identifier">priority_props</span> <span class="special">&gt;()</span> <span class="special">);</span>
 386     <span class="identifier">props</span><span class="special">.</span><span class="identifier">name</span> <span class="special">=</span> <span class="identifier">name</span><span class="special">;</span>
 387     <span class="identifier">props</span><span class="special">.</span><span class="identifier">set_priority</span><span class="special">(</span> <span class="identifier">priority</span><span class="special">);</span>
 388     <span class="keyword">return</span> <span class="identifier">fiber</span><span class="special">;</span>
 389 <span class="special">}</span>
 390 </pre>
 391 <p>
 392     </p>
 393 <p>
 394       Launching a new fiber schedules that fiber as ready, but does <span class="emphasis"><em>not</em></span>
 395       immediately enter its <span class="emphasis"><em>fiber-function</em></span>. The current fiber
 396       retains control until it blocks (or yields, or terminates) for some other reason.
 397       As shown in the <code class="computeroutput"><span class="identifier">launch</span><span class="special">()</span></code>
 398       function above, it is reasonable to launch a fiber and immediately set relevant
 399       properties -- such as, for instance, its priority. Your custom scheduler can
 400       then make use of this information next time the fiber manager calls <a class="link" href="scheduling.html#algorithm_with_properties_pick_next"><code class="computeroutput">algorithm_with_properties::pick_next()</code></a>.
 401     </p>
 402 <div class="footnotes">
 403 <br><hr width="100" align="left">
 404 <div class="footnote"><p><sup>[<a name="ftn.fiber.custom.f0" href="#fiber.custom.f0" class="para">9</a>] </sup>
 405         A previous version of the Fiber library implicitly tracked an int priority
 406         for each fiber, even though the default scheduler ignored it. This has been
 407         dropped, since the library now supports arbitrary scheduler-specific fiber
 408         properties.
 409       </p></div>
 410 </div>
 411 </div>
 412 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 413 <td align="left"></td>
 414 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
 415         Distributed under the Boost Software License, Version 1.0. (See accompanying
 416         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>)
 417       </p>
 418 </div></td>
 419 </tr></table>
 420 <hr>
 421 <div class="spirit-nav">
 422 <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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 423 </div>
 424 </body>
 425 </html>