boost/asio/basic_waitable_timer.hpp

   1 //
   2 // basic_waitable_timer.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10
  11 #ifndef BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP
  12 #define BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19 #include <cstddef>
  20 #include <boost/asio/detail/chrono_time_traits.hpp>
  21 #include <boost/asio/detail/deadline_timer_service.hpp>
  22 #include <boost/asio/detail/handler_type_requirements.hpp>
  23 #include <boost/asio/detail/io_object_impl.hpp>
  24 #include <boost/asio/detail/non_const_lvalue.hpp>
  25 #include <boost/asio/detail/throw_error.hpp>
  26 #include <boost/asio/error.hpp>
  27 #include <boost/asio/executor.hpp>
  28 #include <boost/asio/wait_traits.hpp>
  29
  30 #if defined(BOOST_ASIO_HAS_MOVE)
  31 # include <utility>
  32 #endif // defined(BOOST_ASIO_HAS_MOVE)
  33
  34 #include <boost/asio/detail/push_options.hpp>
  35
  36 namespace boost {
  37 namespace asio {
  38
  39 #if !defined(BOOST_ASIO_BASIC_WAITABLE_TIMER_FWD_DECL)
  40 #define BOOST_ASIO_BASIC_WAITABLE_TIMER_FWD_DECL
  41
  42 // Forward declaration with defaulted arguments.
  43 template <typename Clock,
  44     typename WaitTraits = boost::asio::wait_traits<Clock>,
  45     typename Executor = executor>
  46 class basic_waitable_timer;
  47
  48 #endif // !defined(BOOST_ASIO_BASIC_WAITABLE_TIMER_FWD_DECL)
  49
  50 /// Provides waitable timer functionality.
  51 /**
  52  * The basic_waitable_timer class template provides the ability to perform a
  53  * blocking or asynchronous wait for a timer to expire.
  54  *
  55  * A waitable timer is always in one of two states: "expired" or "not expired".
  56  * If the wait() or async_wait() function is called on an expired timer, the
  57  * wait operation will complete immediately.
  58  *
  59  * Most applications will use one of the boost::asio::steady_timer,
  60  * boost::asio::system_timer or boost::asio::high_resolution_timer typedefs.
  61  *
  62  * @note This waitable timer functionality is for use with the C++11 standard
  63  * library's @c &lt;chrono&gt; facility, or with the Boost.Chrono library.
  64  *
  65  * @par Thread Safety
  66  * @e Distinct @e objects: Safe.@n
  67  * @e Shared @e objects: Unsafe.
  68  *
  69  * @par Examples
  70  * Performing a blocking wait (C++11):
  71  * @code
  72  * // Construct a timer without setting an expiry time.
  73  * boost::asio::steady_timer timer(my_context);
  74  *
  75  * // Set an expiry time relative to now.
  76  * timer.expires_after(std::chrono::seconds(5));
  77  *
  78  * // Wait for the timer to expire.
  79  * timer.wait();
  80  * @endcode
  81  *
  82  * @par
  83  * Performing an asynchronous wait (C++11):
  84  * @code
  85  * void handler(const boost::system::error_code& error)
  86  * {
  87  *   if (!error)
  88  *   {
  89  *     // Timer expired.
  90  *   }
  91  * }
  92  *
  93  * ...
  94  *
  95  * // Construct a timer with an absolute expiry time.
  96  * boost::asio::steady_timer timer(my_context,
  97  *     std::chrono::steady_clock::now() + std::chrono::seconds(60));
  98  *
  99  * // Start an asynchronous wait.
 100  * timer.async_wait(handler);
 101  * @endcode
 102  *
 103  * @par Changing an active waitable timer's expiry time
 104  *
 105  * Changing the expiry time of a timer while there are pending asynchronous
 106  * waits causes those wait operations to be cancelled. To ensure that the action
 107  * associated with the timer is performed only once, use something like this:
 108  * used:
 109  *
 110  * @code
 111  * void on_some_event()
 112  * {
 113  *   if (my_timer.expires_after(seconds(5)) > 0)
 114  *   {
 115  *     // We managed to cancel the timer. Start new asynchronous wait.
 116  *     my_timer.async_wait(on_timeout);
 117  *   }
 118  *   else
 119  *   {
 120  *     // Too late, timer has already expired!
 121  *   }
 122  * }
 123  *
 124  * void on_timeout(const boost::system::error_code& e)
 125  * {
 126  *   if (e != boost::asio::error::operation_aborted)
 127  *   {
 128  *     // Timer was not cancelled, take necessary action.
 129  *   }
 130  * }
 131  * @endcode
 132  *
 133  * @li The boost::asio::basic_waitable_timer::expires_after() function
 134  * cancels any pending asynchronous waits, and returns the number of
 135  * asynchronous waits that were cancelled. If it returns 0 then you were too
 136  * late and the wait handler has already been executed, or will soon be
 137  * executed. If it returns 1 then the wait handler was successfully cancelled.
 138  *
 139  * @li If a wait handler is cancelled, the boost::system::error_code passed to
 140  * it contains the value boost::asio::error::operation_aborted.
 141  */
 142 template <typename Clock, typename WaitTraits, typename Executor>
 143 class basic_waitable_timer
 144 {
 145 public:
 146   /// The type of the executor associated with the object.
 147   typedef Executor executor_type;
 148
 149   /// Rebinds the timer type to another executor.
 150   template <typename Executor1>
 151   struct rebind_executor
 152   {
 153     /// The timer type when rebound to the specified executor.
 154     typedef basic_waitable_timer<Clock, WaitTraits, Executor1> other;
 155   };
 156
 157   /// The clock type.
 158   typedef Clock clock_type;
 159
 160   /// The duration type of the clock.
 161   typedef typename clock_type::duration duration;
 162
 163   /// The time point type of the clock.
 164   typedef typename clock_type::time_point time_point;
 165
 166   /// The wait traits type.
 167   typedef WaitTraits traits_type;
 168
 169   /// Constructor.
 170   /**
 171    * This constructor creates a timer without setting an expiry time. The
 172    * expires_at() or expires_after() functions must be called to set an expiry
 173    * time before the timer can be waited on.
 174    *
 175    * @param ex The I/O executor that the timer will use, by default, to
 176    * dispatch handlers for any asynchronous operations performed on the timer.
 177    */
 178   explicit basic_waitable_timer(const executor_type& ex)
 179     : impl_(ex)
 180   {
 181   }
 182
 183   /// Constructor.
 184   /**
 185    * This constructor creates a timer without setting an expiry time. The
 186    * expires_at() or expires_after() functions must be called to set an expiry
 187    * time before the timer can be waited on.
 188    *
 189    * @param context An execution context which provides the I/O executor that
 190    * the timer will use, by default, to dispatch handlers for any asynchronous
 191    * operations performed on the timer.
 192    */
 193   template <typename ExecutionContext>
 194   explicit basic_waitable_timer(ExecutionContext& context,
 195       typename enable_if<
 196         is_convertible<ExecutionContext&, execution_context&>::value
 197       >::type* = 0)
 198     : impl_(context)
 199   {
 200   }
 201
 202   /// Constructor to set a particular expiry time as an absolute time.
 203   /**
 204    * This constructor creates a timer and sets the expiry time.
 205    *
 206    * @param ex The I/O executor object that the timer will use, by default, to
 207    * dispatch handlers for any asynchronous operations performed on the timer.
 208    *
 209    * @param expiry_time The expiry time to be used for the timer, expressed
 210    * as an absolute time.
 211    */
 212   basic_waitable_timer(const executor_type& ex, const time_point& expiry_time)
 213     : impl_(ex)
 214   {
 215     boost::system::error_code ec;
 216     impl_.get_service().expires_at(impl_.get_implementation(), expiry_time, ec);
 217     boost::asio::detail::throw_error(ec, "expires_at");
 218   }
 219
 220   /// Constructor to set a particular expiry time as an absolute time.
 221   /**
 222    * This constructor creates a timer and sets the expiry time.
 223    *
 224    * @param context An execution context which provides the I/O executor that
 225    * the timer will use, by default, to dispatch handlers for any asynchronous
 226    * operations performed on the timer.
 227    *
 228    * @param expiry_time The expiry time to be used for the timer, expressed
 229    * as an absolute time.
 230    */
 231   template <typename ExecutionContext>
 232   explicit basic_waitable_timer(ExecutionContext& context,
 233       const time_point& expiry_time,
 234       typename enable_if<
 235         is_convertible<ExecutionContext&, execution_context&>::value
 236       >::type* = 0)
 237     : impl_(context)
 238   {
 239     boost::system::error_code ec;
 240     impl_.get_service().expires_at(impl_.get_implementation(), expiry_time, ec);
 241     boost::asio::detail::throw_error(ec, "expires_at");
 242   }
 243
 244   /// Constructor to set a particular expiry time relative to now.
 245   /**
 246    * This constructor creates a timer and sets the expiry time.
 247    *
 248    * @param ex The I/O executor that the timer will use, by default, to
 249    * dispatch handlers for any asynchronous operations performed on the timer.
 250    *
 251    * @param expiry_time The expiry time to be used for the timer, relative to
 252    * now.
 253    */
 254   basic_waitable_timer(const executor_type& ex, const duration& expiry_time)
 255     : impl_(ex)
 256   {
 257     boost::system::error_code ec;
 258     impl_.get_service().expires_after(
 259         impl_.get_implementation(), expiry_time, ec);
 260     boost::asio::detail::throw_error(ec, "expires_after");
 261   }
 262
 263   /// Constructor to set a particular expiry time relative to now.
 264   /**
 265    * This constructor creates a timer and sets the expiry time.
 266    *
 267    * @param context An execution context which provides the I/O executor that
 268    * the timer will use, by default, to dispatch handlers for any asynchronous
 269    * operations performed on the timer.
 270    *
 271    * @param expiry_time The expiry time to be used for the timer, relative to
 272    * now.
 273    */
 274   template <typename ExecutionContext>
 275   explicit basic_waitable_timer(ExecutionContext& context,
 276       const duration& expiry_time,
 277       typename enable_if<
 278         is_convertible<ExecutionContext&, execution_context&>::value
 279       >::type* = 0)
 280     : impl_(context)
 281   {
 282     boost::system::error_code ec;
 283     impl_.get_service().expires_after(
 284         impl_.get_implementation(), expiry_time, ec);
 285     boost::asio::detail::throw_error(ec, "expires_after");
 286   }
 287
 288 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 289   /// Move-construct a basic_waitable_timer from another.
 290   /**
 291    * This constructor moves a timer from one object to another.
 292    *
 293    * @param other The other basic_waitable_timer object from which the move will
 294    * occur.
 295    *
 296    * @note Following the move, the moved-from object is in the same state as if
 297    * constructed using the @c basic_waitable_timer(const executor_type&)
 298    * constructor.
 299    */
 300   basic_waitable_timer(basic_waitable_timer&& other)
 301     : impl_(std::move(other.impl_))
 302   {
 303   }
 304
 305   /// Move-assign a basic_waitable_timer from another.
 306   /**
 307    * This assignment operator moves a timer from one object to another. Cancels
 308    * any outstanding asynchronous operations associated with the target object.
 309    *
 310    * @param other The other basic_waitable_timer object from which the move will
 311    * occur.
 312    *
 313    * @note Following the move, the moved-from object is in the same state as if
 314    * constructed using the @c basic_waitable_timer(const executor_type&)
 315    * constructor.
 316    */
 317   basic_waitable_timer& operator=(basic_waitable_timer&& other)
 318   {
 319     impl_ = std::move(other.impl_);
 320     return *this;
 321   }
 322 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 323
 324   /// Destroys the timer.
 325   /**
 326    * This function destroys the timer, cancelling any outstanding asynchronous
 327    * wait operations associated with the timer as if by calling @c cancel.
 328    */
 329   ~basic_waitable_timer()
 330   {
 331   }
 332
 333   /// Get the executor associated with the object.
 334   executor_type get_executor() BOOST_ASIO_NOEXCEPT
 335   {
 336     return impl_.get_executor();
 337   }
 338
 339   /// Cancel any asynchronous operations that are waiting on the timer.
 340   /**
 341    * This function forces the completion of any pending asynchronous wait
 342    * operations against the timer. The handler for each cancelled operation will
 343    * be invoked with the boost::asio::error::operation_aborted error code.
 344    *
 345    * Cancelling the timer does not change the expiry time.
 346    *
 347    * @return The number of asynchronous operations that were cancelled.
 348    *
 349    * @throws boost::system::system_error Thrown on failure.
 350    *
 351    * @note If the timer has already expired when cancel() is called, then the
 352    * handlers for asynchronous wait operations will:
 353    *
 354    * @li have already been invoked; or
 355    *
 356    * @li have been queued for invocation in the near future.
 357    *
 358    * These handlers can no longer be cancelled, and therefore are passed an
 359    * error code that indicates the successful completion of the wait operation.
 360    */
 361   std::size_t cancel()
 362   {
 363     boost::system::error_code ec;
 364     std::size_t s = impl_.get_service().cancel(impl_.get_implementation(), ec);
 365     boost::asio::detail::throw_error(ec, "cancel");
 366     return s;
 367   }
 368
 369 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 370   /// (Deprecated: Use non-error_code overload.) Cancel any asynchronous
 371   /// operations that are waiting on the timer.
 372   /**
 373    * This function forces the completion of any pending asynchronous wait
 374    * operations against the timer. The handler for each cancelled operation will
 375    * be invoked with the boost::asio::error::operation_aborted error code.
 376    *
 377    * Cancelling the timer does not change the expiry time.
 378    *
 379    * @param ec Set to indicate what error occurred, if any.
 380    *
 381    * @return The number of asynchronous operations that were cancelled.
 382    *
 383    * @note If the timer has already expired when cancel() is called, then the
 384    * handlers for asynchronous wait operations will:
 385    *
 386    * @li have already been invoked; or
 387    *
 388    * @li have been queued for invocation in the near future.
 389    *
 390    * These handlers can no longer be cancelled, and therefore are passed an
 391    * error code that indicates the successful completion of the wait operation.
 392    */
 393   std::size_t cancel(boost::system::error_code& ec)
 394   {
 395     return impl_.get_service().cancel(impl_.get_implementation(), ec);
 396   }
 397 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 398
 399   /// Cancels one asynchronous operation that is waiting on the timer.
 400   /**
 401    * This function forces the completion of one pending asynchronous wait
 402    * operation against the timer. Handlers are cancelled in FIFO order. The
 403    * handler for the cancelled operation will be invoked with the
 404    * boost::asio::error::operation_aborted error code.
 405    *
 406    * Cancelling the timer does not change the expiry time.
 407    *
 408    * @return The number of asynchronous operations that were cancelled. That is,
 409    * either 0 or 1.
 410    *
 411    * @throws boost::system::system_error Thrown on failure.
 412    *
 413    * @note If the timer has already expired when cancel_one() is called, then
 414    * the handlers for asynchronous wait operations will:
 415    *
 416    * @li have already been invoked; or
 417    *
 418    * @li have been queued for invocation in the near future.
 419    *
 420    * These handlers can no longer be cancelled, and therefore are passed an
 421    * error code that indicates the successful completion of the wait operation.
 422    */
 423   std::size_t cancel_one()
 424   {
 425     boost::system::error_code ec;
 426     std::size_t s = impl_.get_service().cancel_one(
 427         impl_.get_implementation(), ec);
 428     boost::asio::detail::throw_error(ec, "cancel_one");
 429     return s;
 430   }
 431
 432 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 433   /// (Deprecated: Use non-error_code overload.) Cancels one asynchronous
 434   /// operation that is waiting on the timer.
 435   /**
 436    * This function forces the completion of one pending asynchronous wait
 437    * operation against the timer. Handlers are cancelled in FIFO order. The
 438    * handler for the cancelled operation will be invoked with the
 439    * boost::asio::error::operation_aborted error code.
 440    *
 441    * Cancelling the timer does not change the expiry time.
 442    *
 443    * @param ec Set to indicate what error occurred, if any.
 444    *
 445    * @return The number of asynchronous operations that were cancelled. That is,
 446    * either 0 or 1.
 447    *
 448    * @note If the timer has already expired when cancel_one() is called, then
 449    * the handlers for asynchronous wait operations will:
 450    *
 451    * @li have already been invoked; or
 452    *
 453    * @li have been queued for invocation in the near future.
 454    *
 455    * These handlers can no longer be cancelled, and therefore are passed an
 456    * error code that indicates the successful completion of the wait operation.
 457    */
 458   std::size_t cancel_one(boost::system::error_code& ec)
 459   {
 460     return impl_.get_service().cancel_one(impl_.get_implementation(), ec);
 461   }
 462
 463   /// (Deprecated: Use expiry().) Get the timer's expiry time as an absolute
 464   /// time.
 465   /**
 466    * This function may be used to obtain the timer's current expiry time.
 467    * Whether the timer has expired or not does not affect this value.
 468    */
 469   time_point expires_at() const
 470   {
 471     return impl_.get_service().expires_at(impl_.get_implementation());
 472   }
 473 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 474
 475   /// Get the timer's expiry time as an absolute time.
 476   /**
 477    * This function may be used to obtain the timer's current expiry time.
 478    * Whether the timer has expired or not does not affect this value.
 479    */
 480   time_point expiry() const
 481   {
 482     return impl_.get_service().expiry(impl_.get_implementation());
 483   }
 484
 485   /// Set the timer's expiry time as an absolute time.
 486   /**
 487    * This function sets the expiry time. Any pending asynchronous wait
 488    * operations will be cancelled. The handler for each cancelled operation will
 489    * be invoked with the boost::asio::error::operation_aborted error code.
 490    *
 491    * @param expiry_time The expiry time to be used for the timer.
 492    *
 493    * @return The number of asynchronous operations that were cancelled.
 494    *
 495    * @throws boost::system::system_error Thrown on failure.
 496    *
 497    * @note If the timer has already expired when expires_at() is called, then
 498    * the handlers for asynchronous wait operations will:
 499    *
 500    * @li have already been invoked; or
 501    *
 502    * @li have been queued for invocation in the near future.
 503    *
 504    * These handlers can no longer be cancelled, and therefore are passed an
 505    * error code that indicates the successful completion of the wait operation.
 506    */
 507   std::size_t expires_at(const time_point& expiry_time)
 508   {
 509     boost::system::error_code ec;
 510     std::size_t s = impl_.get_service().expires_at(
 511         impl_.get_implementation(), expiry_time, ec);
 512     boost::asio::detail::throw_error(ec, "expires_at");
 513     return s;
 514   }
 515
 516 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 517   /// (Deprecated: Use non-error_code overload.) Set the timer's expiry time as
 518   /// an absolute time.
 519   /**
 520    * This function sets the expiry time. Any pending asynchronous wait
 521    * operations will be cancelled. The handler for each cancelled operation will
 522    * be invoked with the boost::asio::error::operation_aborted error code.
 523    *
 524    * @param expiry_time The expiry time to be used for the timer.
 525    *
 526    * @param ec Set to indicate what error occurred, if any.
 527    *
 528    * @return The number of asynchronous operations that were cancelled.
 529    *
 530    * @note If the timer has already expired when expires_at() is called, then
 531    * the handlers for asynchronous wait operations will:
 532    *
 533    * @li have already been invoked; or
 534    *
 535    * @li have been queued for invocation in the near future.
 536    *
 537    * These handlers can no longer be cancelled, and therefore are passed an
 538    * error code that indicates the successful completion of the wait operation.
 539    */
 540   std::size_t expires_at(const time_point& expiry_time,
 541       boost::system::error_code& ec)
 542   {
 543     return impl_.get_service().expires_at(
 544         impl_.get_implementation(), expiry_time, ec);
 545   }
 546 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 547
 548   /// Set the timer's expiry time relative to now.
 549   /**
 550    * This function sets the expiry time. Any pending asynchronous wait
 551    * operations will be cancelled. The handler for each cancelled operation will
 552    * be invoked with the boost::asio::error::operation_aborted error code.
 553    *
 554    * @param expiry_time The expiry time to be used for the timer.
 555    *
 556    * @return The number of asynchronous operations that were cancelled.
 557    *
 558    * @throws boost::system::system_error Thrown on failure.
 559    *
 560    * @note If the timer has already expired when expires_after() is called,
 561    * then the handlers for asynchronous wait operations will:
 562    *
 563    * @li have already been invoked; or
 564    *
 565    * @li have been queued for invocation in the near future.
 566    *
 567    * These handlers can no longer be cancelled, and therefore are passed an
 568    * error code that indicates the successful completion of the wait operation.
 569    */
 570   std::size_t expires_after(const duration& expiry_time)
 571   {
 572     boost::system::error_code ec;
 573     std::size_t s = impl_.get_service().expires_after(
 574         impl_.get_implementation(), expiry_time, ec);
 575     boost::asio::detail::throw_error(ec, "expires_after");
 576     return s;
 577   }
 578
 579 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 580   /// (Deprecated: Use expiry().) Get the timer's expiry time relative to now.
 581   /**
 582    * This function may be used to obtain the timer's current expiry time.
 583    * Whether the timer has expired or not does not affect this value.
 584    */
 585   duration expires_from_now() const
 586   {
 587     return impl_.get_service().expires_from_now(impl_.get_implementation());
 588   }
 589
 590   /// (Deprecated: Use expires_after().) Set the timer's expiry time relative
 591   /// to now.
 592   /**
 593    * This function sets the expiry time. Any pending asynchronous wait
 594    * operations will be cancelled. The handler for each cancelled operation will
 595    * be invoked with the boost::asio::error::operation_aborted error code.
 596    *
 597    * @param expiry_time The expiry time to be used for the timer.
 598    *
 599    * @return The number of asynchronous operations that were cancelled.
 600    *
 601    * @throws boost::system::system_error Thrown on failure.
 602    *
 603    * @note If the timer has already expired when expires_from_now() is called,
 604    * then the handlers for asynchronous wait operations will:
 605    *
 606    * @li have already been invoked; or
 607    *
 608    * @li have been queued for invocation in the near future.
 609    *
 610    * These handlers can no longer be cancelled, and therefore are passed an
 611    * error code that indicates the successful completion of the wait operation.
 612    */
 613   std::size_t expires_from_now(const duration& expiry_time)
 614   {
 615     boost::system::error_code ec;
 616     std::size_t s = impl_.get_service().expires_from_now(
 617         impl_.get_implementation(), expiry_time, ec);
 618     boost::asio::detail::throw_error(ec, "expires_from_now");
 619     return s;
 620   }
 621
 622   /// (Deprecated: Use expires_after().) Set the timer's expiry time relative
 623   /// to now.
 624   /**
 625    * This function sets the expiry time. Any pending asynchronous wait
 626    * operations will be cancelled. The handler for each cancelled operation will
 627    * be invoked with the boost::asio::error::operation_aborted error code.
 628    *
 629    * @param expiry_time The expiry time to be used for the timer.
 630    *
 631    * @param ec Set to indicate what error occurred, if any.
 632    *
 633    * @return The number of asynchronous operations that were cancelled.
 634    *
 635    * @note If the timer has already expired when expires_from_now() is called,
 636    * then the handlers for asynchronous wait operations will:
 637    *
 638    * @li have already been invoked; or
 639    *
 640    * @li have been queued for invocation in the near future.
 641    *
 642    * These handlers can no longer be cancelled, and therefore are passed an
 643    * error code that indicates the successful completion of the wait operation.
 644    */
 645   std::size_t expires_from_now(const duration& expiry_time,
 646       boost::system::error_code& ec)
 647   {
 648     return impl_.get_service().expires_from_now(
 649         impl_.get_implementation(), expiry_time, ec);
 650   }
 651 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 652
 653   /// Perform a blocking wait on the timer.
 654   /**
 655    * This function is used to wait for the timer to expire. This function
 656    * blocks and does not return until the timer has expired.
 657    *
 658    * @throws boost::system::system_error Thrown on failure.
 659    */
 660   void wait()
 661   {
 662     boost::system::error_code ec;
 663     impl_.get_service().wait(impl_.get_implementation(), ec);
 664     boost::asio::detail::throw_error(ec, "wait");
 665   }
 666
 667   /// Perform a blocking wait on the timer.
 668   /**
 669    * This function is used to wait for the timer to expire. This function
 670    * blocks and does not return until the timer has expired.
 671    *
 672    * @param ec Set to indicate what error occurred, if any.
 673    */
 674   void wait(boost::system::error_code& ec)
 675   {
 676     impl_.get_service().wait(impl_.get_implementation(), ec);
 677   }
 678
 679   /// Start an asynchronous wait on the timer.
 680   /**
 681    * This function may be used to initiate an asynchronous wait against the
 682    * timer. It always returns immediately.
 683    *
 684    * For each call to async_wait(), the supplied handler will be called exactly
 685    * once. The handler will be called when:
 686    *
 687    * @li The timer has expired.
 688    *
 689    * @li The timer was cancelled, in which case the handler is passed the error
 690    * code boost::asio::error::operation_aborted.
 691    *
 692    * @param handler The handler to be called when the timer expires. Copies
 693    * will be made of the handler as required. The function signature of the
 694    * handler must be:
 695    * @code void handler(
 696    *   const boost::system::error_code& error // Result of operation.
 697    * ); @endcode
 698    * Regardless of whether the asynchronous operation completes immediately or
 699    * not, the handler will not be invoked from within this function. On
 700    * immediate completion, invocation of the handler will be performed in a
 701    * manner equivalent to using boost::asio::post().
 702    */
 703   template <
 704       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code))
 705         WaitHandler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 706   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WaitHandler,
 707       void (boost::system::error_code))
 708   async_wait(
 709       BOOST_ASIO_MOVE_ARG(WaitHandler) handler
 710         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 711   {
 712     return async_initiate<WaitHandler, void (boost::system::error_code)>(
 713         initiate_async_wait(this), handler);
 714   }
 715
 716 private:
 717   // Disallow copying and assignment.
 718   basic_waitable_timer(const basic_waitable_timer&) BOOST_ASIO_DELETED;
 719   basic_waitable_timer& operator=(
 720       const basic_waitable_timer&) BOOST_ASIO_DELETED;
 721
 722   class initiate_async_wait
 723   {
 724   public:
 725     typedef Executor executor_type;
 726
 727     explicit initiate_async_wait(basic_waitable_timer* self)
 728       : self_(self)
 729     {
 730     }
 731
 732     executor_type get_executor() const BOOST_ASIO_NOEXCEPT
 733     {
 734       return self_->get_executor();
 735     }
 736
 737     template <typename WaitHandler>
 738     void operator()(BOOST_ASIO_MOVE_ARG(WaitHandler) handler) const
 739     {
 740       // If you get an error on the following line it means that your handler
 741       // does not meet the documented type requirements for a WaitHandler.
 742       BOOST_ASIO_WAIT_HANDLER_CHECK(WaitHandler, handler) type_check;
 743
 744       detail::non_const_lvalue<WaitHandler> handler2(handler);
 745       self_->impl_.get_service().async_wait(
 746           self_->impl_.get_implementation(), handler2.value,
 747           self_->impl_.get_implementation_executor());
 748     }
 749
 750   private:
 751     basic_waitable_timer* self_;
 752   };
 753
 754   detail::io_object_impl<
 755     detail::deadline_timer_service<
 756       detail::chrono_time_traits<Clock, WaitTraits> >,
 757     executor_type > impl_;
 758 };
 759
 760 } // namespace asio
 761 } // namespace boost
 762
 763 #include <boost/asio/detail/pop_options.hpp>
 764
 765 #endif // BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP