doc/html/boost_asio/reference/basic_waitable_timer.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>basic_waitable_timer</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="../reference.html" title="Reference">
   9 <link rel="prev" href="basic_streambuf_ref/size.html" title="basic_streambuf_ref::size">
  10 <link rel="next" href="basic_waitable_timer/async_wait.html" title="basic_waitable_timer::async_wait">
  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="basic_streambuf_ref/size.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="basic_waitable_timer/async_wait.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.reference.basic_waitable_timer"></a><a class="link" href="basic_waitable_timer.html" title="basic_waitable_timer">basic_waitable_timer</a>
  28 </h3></div></div></div>
  29 <p>
  30         Provides waitable timer functionality.
  31       </p>
  32 <pre class="programlisting">template&lt;
  33     typename Clock,
  34     typename <a class="link" href="WaitTraits.html" title="Wait traits requirements">WaitTraits</a>,
  35     typename <a class="link" href="Executor1.html" title="Executor requirements">Executor</a>&gt;
  36 class basic_waitable_timer
  37 </pre>
  38 <h5>
  39 <a name="boost_asio.reference.basic_waitable_timer.h0"></a>
  40         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.types"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.types">Types</a>
  41       </h5>
  42 <div class="informaltable"><table class="table">
  43 <colgroup>
  44 <col>
  45 <col>
  46 </colgroup>
  47 <thead><tr>
  48 <th>
  49                 <p>
  50                   Name
  51                 </p>
  52               </th>
  53 <th>
  54                 <p>
  55                   Description
  56                 </p>
  57               </th>
  58 </tr></thead>
  59 <tbody>
  60 <tr>
  61 <td>
  62                 <p>
  63                   <a class="link" href="basic_waitable_timer__rebind_executor.html" title="basic_waitable_timer::rebind_executor"><span class="bold"><strong>rebind_executor</strong></span></a>
  64                 </p>
  65               </td>
  66 <td>
  67                 <p>
  68                   Rebinds the timer type to another executor.
  69                 </p>
  70               </td>
  71 </tr>
  72 <tr>
  73 <td>
  74                 <p>
  75                   <a class="link" href="basic_waitable_timer/clock_type.html" title="basic_waitable_timer::clock_type"><span class="bold"><strong>clock_type</strong></span></a>
  76                 </p>
  77               </td>
  78 <td>
  79                 <p>
  80                   The clock type.
  81                 </p>
  82               </td>
  83 </tr>
  84 <tr>
  85 <td>
  86                 <p>
  87                   <a class="link" href="basic_waitable_timer/duration.html" title="basic_waitable_timer::duration"><span class="bold"><strong>duration</strong></span></a>
  88                 </p>
  89               </td>
  90 <td>
  91                 <p>
  92                   The duration type of the clock.
  93                 </p>
  94               </td>
  95 </tr>
  96 <tr>
  97 <td>
  98                 <p>
  99                   <a class="link" href="basic_waitable_timer/executor_type.html" title="basic_waitable_timer::executor_type"><span class="bold"><strong>executor_type</strong></span></a>
 100                 </p>
 101               </td>
 102 <td>
 103                 <p>
 104                   The type of the executor associated with the object.
 105                 </p>
 106               </td>
 107 </tr>
 108 <tr>
 109 <td>
 110                 <p>
 111                   <a class="link" href="basic_waitable_timer/time_point.html" title="basic_waitable_timer::time_point"><span class="bold"><strong>time_point</strong></span></a>
 112                 </p>
 113               </td>
 114 <td>
 115                 <p>
 116                   The time point type of the clock.
 117                 </p>
 118               </td>
 119 </tr>
 120 <tr>
 121 <td>
 122                 <p>
 123                   <a class="link" href="basic_waitable_timer/traits_type.html" title="basic_waitable_timer::traits_type"><span class="bold"><strong>traits_type</strong></span></a>
 124                 </p>
 125               </td>
 126 <td>
 127                 <p>
 128                   The wait traits type.
 129                 </p>
 130               </td>
 131 </tr>
 132 </tbody>
 133 </table></div>
 134 <h5>
 135 <a name="boost_asio.reference.basic_waitable_timer.h1"></a>
 136         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.member_functions"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.member_functions">Member
 137         Functions</a>
 138       </h5>
 139 <div class="informaltable"><table class="table">
 140 <colgroup>
 141 <col>
 142 <col>
 143 </colgroup>
 144 <thead><tr>
 145 <th>
 146                 <p>
 147                   Name
 148                 </p>
 149               </th>
 150 <th>
 151                 <p>
 152                   Description
 153                 </p>
 154               </th>
 155 </tr></thead>
 156 <tbody>
 157 <tr>
 158 <td>
 159                 <p>
 160                   <a class="link" href="basic_waitable_timer/async_wait.html" title="basic_waitable_timer::async_wait"><span class="bold"><strong>async_wait</strong></span></a>
 161                 </p>
 162               </td>
 163 <td>
 164                 <p>
 165                   Start an asynchronous wait on the timer.
 166                 </p>
 167               </td>
 168 </tr>
 169 <tr>
 170 <td>
 171                 <p>
 172                   <a class="link" href="basic_waitable_timer/basic_waitable_timer.html" title="basic_waitable_timer::basic_waitable_timer"><span class="bold"><strong>basic_waitable_timer</strong></span></a>
 173                 </p>
 174               </td>
 175 <td>
 176                 <p>
 177                   Constructor. <br> <span class="silver"> &#8212;</span><br> Constructor to set a particular expiry
 178                   time as an absolute time. <br> <span class="silver"> &#8212;</span><br> Constructor to set a particular
 179                   expiry time relative to now. <br> <span class="silver"> &#8212;</span><br> Move-construct a basic_waitable_timer
 180                   from another.
 181                 </p>
 182               </td>
 183 </tr>
 184 <tr>
 185 <td>
 186                 <p>
 187                   <a class="link" href="basic_waitable_timer/cancel.html" title="basic_waitable_timer::cancel"><span class="bold"><strong>cancel</strong></span></a>
 188                 </p>
 189               </td>
 190 <td>
 191                 <p>
 192                   Cancel any asynchronous operations that are waiting on the timer.
 193                   <br> <span class="silver"> &#8212;</span><br> (Deprecated: Use non-error_code overload.) Cancel
 194                   any asynchronous operations that are waiting on the timer.
 195                 </p>
 196               </td>
 197 </tr>
 198 <tr>
 199 <td>
 200                 <p>
 201                   <a class="link" href="basic_waitable_timer/cancel_one.html" title="basic_waitable_timer::cancel_one"><span class="bold"><strong>cancel_one</strong></span></a>
 202                 </p>
 203               </td>
 204 <td>
 205                 <p>
 206                   Cancels one asynchronous operation that is waiting on the timer.
 207                   <br> <span class="silver"> &#8212;</span><br> (Deprecated: Use non-error_code overload.) Cancels
 208                   one asynchronous operation that is waiting on the timer.
 209                 </p>
 210               </td>
 211 </tr>
 212 <tr>
 213 <td>
 214                 <p>
 215                   <a class="link" href="basic_waitable_timer/expires_after.html" title="basic_waitable_timer::expires_after"><span class="bold"><strong>expires_after</strong></span></a>
 216                 </p>
 217               </td>
 218 <td>
 219                 <p>
 220                   Set the timer's expiry time relative to now.
 221                 </p>
 222               </td>
 223 </tr>
 224 <tr>
 225 <td>
 226                 <p>
 227                   <a class="link" href="basic_waitable_timer/expires_at.html" title="basic_waitable_timer::expires_at"><span class="bold"><strong>expires_at</strong></span></a>
 228                 </p>
 229               </td>
 230 <td>
 231                 <p>
 232                   (Deprecated: Use expiry().) Get the timer's expiry time as an absolute
 233                   time. <br> <span class="silver"> &#8212;</span><br> Set the timer's expiry time as an absolute
 234                   time. <br> <span class="silver"> &#8212;</span><br> (Deprecated: Use non-error_code overload.)
 235                   Set the timer's expiry time as an absolute time.
 236                 </p>
 237               </td>
 238 </tr>
 239 <tr>
 240 <td>
 241                 <p>
 242                   <a class="link" href="basic_waitable_timer/expires_from_now.html" title="basic_waitable_timer::expires_from_now"><span class="bold"><strong>expires_from_now</strong></span></a>
 243                 </p>
 244               </td>
 245 <td>
 246                 <p>
 247                   (Deprecated: Use expiry().) Get the timer's expiry time relative
 248                   to now. <br> <span class="silver"> &#8212;</span><br> (Deprecated: Use expires_after().) Set the
 249                   timer's expiry time relative to now.
 250                 </p>
 251               </td>
 252 </tr>
 253 <tr>
 254 <td>
 255                 <p>
 256                   <a class="link" href="basic_waitable_timer/expiry.html" title="basic_waitable_timer::expiry"><span class="bold"><strong>expiry</strong></span></a>
 257                 </p>
 258               </td>
 259 <td>
 260                 <p>
 261                   Get the timer's expiry time as an absolute time.
 262                 </p>
 263               </td>
 264 </tr>
 265 <tr>
 266 <td>
 267                 <p>
 268                   <a class="link" href="basic_waitable_timer/get_executor.html" title="basic_waitable_timer::get_executor"><span class="bold"><strong>get_executor</strong></span></a>
 269                 </p>
 270               </td>
 271 <td>
 272                 <p>
 273                   Get the executor associated with the object.
 274                 </p>
 275               </td>
 276 </tr>
 277 <tr>
 278 <td>
 279                 <p>
 280                   <a class="link" href="basic_waitable_timer/operator_eq_.html" title="basic_waitable_timer::operator="><span class="bold"><strong>operator=</strong></span></a>
 281                 </p>
 282               </td>
 283 <td>
 284                 <p>
 285                   Move-assign a basic_waitable_timer from another.
 286                 </p>
 287               </td>
 288 </tr>
 289 <tr>
 290 <td>
 291                 <p>
 292                   <a class="link" href="basic_waitable_timer/wait.html" title="basic_waitable_timer::wait"><span class="bold"><strong>wait</strong></span></a>
 293                 </p>
 294               </td>
 295 <td>
 296                 <p>
 297                   Perform a blocking wait on the timer.
 298                 </p>
 299               </td>
 300 </tr>
 301 <tr>
 302 <td>
 303                 <p>
 304                   <a class="link" href="basic_waitable_timer/_basic_waitable_timer.html" title="basic_waitable_timer::~basic_waitable_timer"><span class="bold"><strong>~basic_waitable_timer</strong></span></a>
 305                 </p>
 306               </td>
 307 <td>
 308                 <p>
 309                   Destroys the timer.
 310                 </p>
 311               </td>
 312 </tr>
 313 </tbody>
 314 </table></div>
 315 <p>
 316         The <a class="link" href="basic_waitable_timer.html" title="basic_waitable_timer"><code class="computeroutput">basic_waitable_timer</code></a>
 317         class template provides the ability to perform a blocking or asynchronous
 318         wait for a timer to expire.
 319       </p>
 320 <p>
 321         A waitable timer is always in one of two states: "expired" or "not
 322         expired". If the <code class="computeroutput">wait()</code> or <code class="computeroutput">async_wait()</code> function
 323         is called on an expired timer, the wait operation will complete immediately.
 324       </p>
 325 <p>
 326         Most applications will use one of the <a class="link" href="steady_timer.html" title="steady_timer"><code class="computeroutput">steady_timer</code></a>,
 327         <a class="link" href="system_timer.html" title="system_timer"><code class="computeroutput">system_timer</code></a>
 328         or <a class="link" href="high_resolution_timer.html" title="high_resolution_timer"><code class="computeroutput">high_resolution_timer</code></a>
 329         typedefs.
 330       </p>
 331 <h5>
 332 <a name="boost_asio.reference.basic_waitable_timer.h2"></a>
 333         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.remarks"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.remarks">Remarks</a>
 334       </h5>
 335 <p>
 336         This waitable timer functionality is for use with the C++11 standard library's
 337         <code class="computeroutput">&lt;chrono&gt;</code> facility, or with the Boost.Chrono library.
 338       </p>
 339 <h5>
 340 <a name="boost_asio.reference.basic_waitable_timer.h3"></a>
 341         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.thread_safety"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.thread_safety">Thread
 342         Safety</a>
 343       </h5>
 344 <p>
 345         <span class="emphasis"><em>Distinct</em></span> <span class="emphasis"><em>objects:</em></span> Safe.
 346       </p>
 347 <p>
 348         <span class="emphasis"><em>Shared</em></span> <span class="emphasis"><em>objects:</em></span> Unsafe.
 349       </p>
 350 <h5>
 351 <a name="boost_asio.reference.basic_waitable_timer.h4"></a>
 352         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.examples"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.examples">Examples</a>
 353       </h5>
 354 <p>
 355         Performing a blocking wait (C++11):
 356       </p>
 357 <pre class="programlisting">// Construct a timer without setting an expiry time.
 358 boost::asio::steady_timer timer(my_context);
 359
 360 // Set an expiry time relative to now.
 361 timer.expires_after(std::chrono::seconds(5));
 362
 363 // Wait for the timer to expire.
 364 timer.wait();
 365 </pre>
 366 <p>
 367         Performing an asynchronous wait (C++11):
 368       </p>
 369 <pre class="programlisting">void handler(const boost::system::error_code&amp; error)
 370 {
 371   if (!error)
 372   {
 373     // Timer expired.
 374   }
 375 }
 376
 377 ...
 378
 379 // Construct a timer with an absolute expiry time.
 380 boost::asio::steady_timer timer(my_context,
 381     std::chrono::steady_clock::now() + std::chrono::seconds(60));
 382
 383 // Start an asynchronous wait.
 384 timer.async_wait(handler);
 385 </pre>
 386 <h5>
 387 <a name="boost_asio.reference.basic_waitable_timer.h5"></a>
 388         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.changing_an_active_waitable_timer_s_expiry_time"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.changing_an_active_waitable_timer_s_expiry_time">Changing
 389         an active waitable timer's expiry time</a>
 390       </h5>
 391 <p>
 392         Changing the expiry time of a timer while there are pending asynchronous
 393         waits causes those wait operations to be cancelled. To ensure that the action
 394         associated with the timer is performed only once, use something like this:
 395         used:
 396       </p>
 397 <pre class="programlisting">void on_some_event()
 398 {
 399   if (my_timer.expires_after(seconds(5)) &gt; 0)
 400   {
 401     // We managed to cancel the timer. Start new asynchronous wait.
 402     my_timer.async_wait(on_timeout);
 403   }
 404   else
 405   {
 406     // Too late, timer has already expired!
 407   }
 408 }
 409
 410 void on_timeout(const boost::system::error_code&amp; e)
 411 {
 412   if (e != boost::asio::error::operation_aborted)
 413   {
 414     // Timer was not cancelled, take necessary action.
 415   }
 416 }
 417 </pre>
 418 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 419 <li class="listitem">
 420             The <code class="computeroutput">boost::asio::basic_waitable_timer::expires_after()</code> function
 421             cancels any pending asynchronous waits, and returns the number of asynchronous
 422             waits that were cancelled. If it returns 0 then you were too late and
 423             the wait handler has already been executed, or will soon be executed.
 424             If it returns 1 then the wait handler was successfully cancelled.
 425           </li>
 426 <li class="listitem">
 427             If a wait handler is cancelled, the boost::system::error_code passed
 428             to it contains the value <code class="computeroutput">boost::asio::error::operation_aborted</code>.
 429           </li>
 430 </ul></div>
 431 <h5>
 432 <a name="boost_asio.reference.basic_waitable_timer.h6"></a>
 433         <span class="phrase"><a name="boost_asio.reference.basic_waitable_timer.requirements"></a></span><a class="link" href="basic_waitable_timer.html#boost_asio.reference.basic_waitable_timer.requirements">Requirements</a>
 434       </h5>
 435 <p>
 436         <span class="emphasis"><em>Header: </em></span><code class="literal">boost/asio/basic_waitable_timer.hpp</code>
 437       </p>
 438 <p>
 439         <span class="emphasis"><em>Convenience header: </em></span><code class="literal">boost/asio.hpp</code>
 440       </p>
 441 </div>
 442 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 443 <td align="left"></td>
 444 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2019 Christopher M. Kohlhoff<p>
 445         Distributed under the Boost Software License, Version 1.0. (See accompanying
 446         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>)
 447       </p>
 448 </div></td>
 449 </tr></table>
 450 <hr>
 451 <div class="spirit-nav">
 452 <a accesskey="p" href="basic_streambuf_ref/size.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="basic_waitable_timer/async_wait.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 453 </div>
 454 </body>
 455 </html>