doc/html/boost_asio/tutorial/tuttimer3.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Timer.3 - Binding arguments to a handler</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../tutorial.html" title="Tutorial">
   9 <link rel="prev" href="tuttimer2/src.html" title="Source listing for Timer.2">
  10 <link rel="next" href="tuttimer3/src.html" title="Source listing for Timer.3">
  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="tuttimer2/src.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tuttimer3/src.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_asio.tutorial.tuttimer3"></a><a class="link" href="tuttimer3.html" title="Timer.3 - Binding arguments to a handler">Timer.3 - Binding arguments
  28       to a handler</a>
  29 </h3></div></div></div>
  30 <p>
  31         In this tutorial we will modify the program from tutorial Timer.2 so that
  32         the timer fires once a second. This will show how to pass additional parameters
  33         to your handler function.
  34       </p>
  35 <pre class="programlisting"><span class="special">#</span><span class="identifier">include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
  36 <span class="special">#</span><span class="identifier">include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  37 <span class="special">#</span><span class="identifier">include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  38 <span class="special">#</span><span class="identifier">include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">date_time</span><span class="special">/</span><span class="identifier">posix_time</span><span class="special">/</span><span class="identifier">posix_time</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  39 </pre>
  40 <p>
  41         To implement a repeating timer using asio you need to change the timer's
  42         expiry time in your callback function, and to then start a new asynchronous
  43         wait. Obviously this means that the callback function will need to be able
  44         to access the timer object. To this end we add two new parameters to the
  45         <code class="computeroutput"><span class="identifier">print</span></code> function:
  46       </p>
  47 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  48 <li class="listitem">
  49             A pointer to a timer object.
  50           </li>
  51 <li class="listitem">
  52             A counter so that we can stop the program when the timer fires for the
  53             sixth time.
  54           </li>
  55 </ul></div>
  56 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">print</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span><span class="special">&amp;</span> <span class="comment">/*e*/</span><span class="special">,</span>
  57     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">deadline_timer</span><span class="special">*</span> <span class="identifier">t</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">count</span><span class="special">)</span>
  58 <span class="special">{</span>
  59 </pre>
  60 <p>
  61         As mentioned above, this tutorial program uses a counter to stop running
  62         when the timer fires for the sixth time. However you will observe that there
  63         is no explicit call to ask the io_service to stop. Recall that in tutorial
  64         Timer.2 we learnt that the <a class="link" href="../reference/io_service/run.html" title="io_service::run">io_service::run()</a>
  65         function completes when there is no more "work" to do. By not starting
  66         a new asynchronous wait on the timer when <code class="computeroutput"><span class="identifier">count</span></code>
  67         reaches 5, the io_service will run out of work and stop running.
  68       </p>
  69 <pre class="programlisting">  <span class="keyword">if</span> <span class="special">(*</span><span class="identifier">count</span> <span class="special">&lt;</span> <span class="number">5</span><span class="special">)</span>
  70   <span class="special">{</span>
  71     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">count</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>
  72     <span class="special">++(*</span><span class="identifier">count</span><span class="special">);</span>
  73 </pre>
  74 <p>
  75         Next we move the expiry time for the timer along by one second from the previous
  76         expiry time. By calculating the new expiry time relative to the old, we can
  77         ensure that the timer does not drift away from the whole-second mark due
  78         to any delays in processing the handler.
  79       </p>
  80 <pre class="programlisting">    <span class="identifier">t</span><span class="special">-&gt;</span><span class="identifier">expires_at</span><span class="special">(</span><span class="identifier">t</span><span class="special">-&gt;</span><span class="identifier">expires_at</span><span class="special">()</span> <span class="special">+</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">1</span><span class="special">));</span>
  81 </pre>
  82 <p>
  83         Then we start a new asynchronous wait on the timer. As you can see, the boost::bind()
  84         function is used to associate the extra parameters with your callback handler.
  85         The <a class="link" href="../reference/basic_deadline_timer/async_wait.html" title="basic_deadline_timer::async_wait">deadline_timer::async_wait()</a>
  86         function expects a handler function (or function object) with the signature
  87         <code class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span><span class="special">&amp;)</span></code>. Binding the additional parameters
  88         converts your <code class="computeroutput"><span class="identifier">print</span></code> function
  89         into a function object that matches the signature correctly.
  90       </p>
  91 <p>
  92         See the <a href="http://www.boost.org/libs/bind/bind.html" target="_top">Boost.Bind
  93         documentation</a> for more information on how to use boost::bind().
  94       </p>
  95 <p>
  96         In this example, the boost::asio::placeholders::error argument to boost::bind()
  97         is a named placeholder for the error object passed to the handler. When initiating
  98         the asynchronous operation, and if using boost::bind(), you must specify
  99         only the arguments that match the handler's parameter list. In tutorial Timer.4
 100         you will see that this placeholder may be elided if the parameter is not
 101         needed by the callback handler.
 102       </p>
 103 <pre class="programlisting">    <span class="identifier">t</span><span class="special">-&gt;</span><span class="identifier">async_wait</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">print</span><span class="special">,</span>
 104           <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">placeholders</span><span class="special">::</span><span class="identifier">error</span><span class="special">,</span> <span class="identifier">t</span><span class="special">,</span> <span class="identifier">count</span><span class="special">));</span>
 105   <span class="special">}</span>
 106 <span class="special">}</span>
 107
 108 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 109 <span class="special">{</span>
 110   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span> <span class="identifier">io</span><span class="special">;</span>
 111 </pre>
 112 <p>
 113         A new <code class="computeroutput"><span class="identifier">count</span></code> variable is added
 114         so that we can stop the program when the timer fires for the sixth time.
 115       </p>
 116 <pre class="programlisting">  <span class="keyword">int</span> <span class="identifier">count</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 117   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">deadline_timer</span> <span class="identifier">t</span><span class="special">(</span><span class="identifier">io</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">1</span><span class="special">));</span>
 118 </pre>
 119 <p>
 120         As in Step 4, when making the call to <a class="link" href="../reference/basic_deadline_timer/async_wait.html" title="basic_deadline_timer::async_wait">deadline_timer::async_wait()</a>
 121         from <code class="computeroutput"><span class="identifier">main</span></code> we bind the additional
 122         parameters needed for the <code class="computeroutput"><span class="identifier">print</span></code>
 123         function.
 124       </p>
 125 <pre class="programlisting">  <span class="identifier">t</span><span class="special">.</span><span class="identifier">async_wait</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">print</span><span class="special">,</span>
 126         <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">placeholders</span><span class="special">::</span><span class="identifier">error</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">t</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">count</span><span class="special">));</span>
 127
 128   <span class="identifier">io</span><span class="special">.</span><span class="identifier">run</span><span class="special">();</span>
 129 </pre>
 130 <p>
 131         Finally, just to prove that the <code class="computeroutput"><span class="identifier">count</span></code>
 132         variable was being used in the <code class="computeroutput"><span class="identifier">print</span></code>
 133         handler function, we will print out its new value.
 134       </p>
 135 <pre class="programlisting">  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Final count is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">count</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>
 136
 137   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 138 <span class="special">}</span>
 139 </pre>
 140 <p>
 141         See the <a class="link" href="tuttimer3/src.html" title="Source listing for Timer.3">full source listing</a>
 142       </p>
 143 <p>
 144         Return to the <a class="link" href="../tutorial.html" title="Tutorial">tutorial index</a>
 145       </p>
 146 <p>
 147         Previous: <a class="link" href="tuttimer2.html" title="Timer.2 - Using a timer asynchronously">Timer.2 - Using a
 148         timer asynchronously</a>
 149       </p>
 150 <p>
 151         Next: <a class="link" href="tuttimer4.html" title="Timer.4 - Using a member function as a handler">Timer.4 - Using a member
 152         function as a handler</a>
 153       </p>
 154 </div>
 155 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 156 <td align="left"></td>
 157 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2017 Christopher M. Kohlhoff<p>
 158         Distributed under the Boost Software License, Version 1.0. (See accompanying
 159         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>)
 160       </p>
 161 </div></td>
 162 </tr></table>
 163 <hr>
 164 <div class="spirit-nav">
 165 <a accesskey="p" href="tuttimer2/src.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tuttimer3/src.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 166 </div>
 167 </body>
 168 </html>