doc/html/boost_asio/reference/basic_deadline_timer.html

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