2 // basic_waitable_timer.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP
12 #define BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #include <boost/asio/basic_io_object.hpp>
21 #include <boost/asio/detail/handler_type_requirements.hpp>
22 #include <boost/asio/detail/throw_error.hpp>
23 #include <boost/asio/error.hpp>
24 #include <boost/asio/wait_traits.hpp>
25 #include <boost/asio/waitable_timer_service.hpp>
27 #include <boost/asio/detail/push_options.hpp>
32 /// Provides waitable timer functionality.
34 * The basic_waitable_timer class template provides the ability to perform a
35 * blocking or asynchronous wait for a timer to expire.
37 * A waitable timer is always in one of two states: "expired" or "not expired".
38 * If the wait() or async_wait() function is called on an expired timer, the
39 * wait operation will complete immediately.
41 * Most applications will use one of the boost::asio::steady_timer,
42 * boost::asio::system_timer or boost::asio::high_resolution_timer typedefs.
44 * @note This waitable timer functionality is for use with the C++11 standard
45 * library's @c <chrono> facility, or with the Boost.Chrono library.
48 * @e Distinct @e objects: Safe.@n
49 * @e Shared @e objects: Unsafe.
52 * Performing a blocking wait (C++11):
54 * // Construct a timer without setting an expiry time.
55 * boost::asio::steady_timer timer(io_service);
57 * // Set an expiry time relative to now.
58 * timer.expires_from_now(std::chrono::seconds(5));
60 * // Wait for the timer to expire.
65 * Performing an asynchronous wait (C++11):
67 * void handler(const boost::system::error_code& error)
77 * // Construct a timer with an absolute expiry time.
78 * boost::asio::steady_timer timer(io_service,
79 * std::chrono::steady_clock::now() + std::chrono::seconds(60));
81 * // Start an asynchronous wait.
82 * timer.async_wait(handler);
85 * @par Changing an active waitable timer's expiry time
87 * Changing the expiry time of a timer while there are pending asynchronous
88 * waits causes those wait operations to be cancelled. To ensure that the action
89 * associated with the timer is performed only once, use something like this:
93 * void on_some_event()
95 * if (my_timer.expires_from_now(seconds(5)) > 0)
97 * // We managed to cancel the timer. Start new asynchronous wait.
98 * my_timer.async_wait(on_timeout);
102 * // Too late, timer has already expired!
106 * void on_timeout(const boost::system::error_code& e)
108 * if (e != boost::asio::error::operation_aborted)
110 * // Timer was not cancelled, take necessary action.
115 * @li The boost::asio::basic_waitable_timer::expires_from_now() function
116 * cancels any pending asynchronous waits, and returns the number of
117 * asynchronous waits that were cancelled. If it returns 0 then you were too
118 * late and the wait handler has already been executed, or will soon be
119 * executed. If it returns 1 then the wait handler was successfully cancelled.
121 * @li If a wait handler is cancelled, the boost::system::error_code passed to
122 * it contains the value boost::asio::error::operation_aborted.
124 template <typename Clock,
125 typename WaitTraits = boost::asio::wait_traits<Clock>,
126 typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits> >
127 class basic_waitable_timer
128 : public basic_io_object<WaitableTimerService>
132 typedef Clock clock_type;
134 /// The duration type of the clock.
135 typedef typename clock_type::duration duration;
137 /// The time point type of the clock.
138 typedef typename clock_type::time_point time_point;
140 /// The wait traits type.
141 typedef WaitTraits traits_type;
145 * This constructor creates a timer without setting an expiry time. The
146 * expires_at() or expires_from_now() functions must be called to set an
147 * expiry time before the timer can be waited on.
149 * @param io_service The io_service object that the timer will use to dispatch
150 * handlers for any asynchronous operations performed on the timer.
152 explicit basic_waitable_timer(boost::asio::io_service& io_service)
153 : basic_io_object<WaitableTimerService>(io_service)
157 /// Constructor to set a particular expiry time as an absolute time.
159 * This constructor creates a timer and sets the expiry time.
161 * @param io_service The io_service object that the timer will use to dispatch
162 * handlers for any asynchronous operations performed on the timer.
164 * @param expiry_time The expiry time to be used for the timer, expressed
165 * as an absolute time.
167 basic_waitable_timer(boost::asio::io_service& io_service,
168 const time_point& expiry_time)
169 : basic_io_object<WaitableTimerService>(io_service)
171 boost::system::error_code ec;
172 this->service.expires_at(this->implementation, expiry_time, ec);
173 boost::asio::detail::throw_error(ec, "expires_at");
176 /// Constructor to set a particular expiry time relative to now.
178 * This constructor creates a timer and sets the expiry time.
180 * @param io_service The io_service object that the timer will use to dispatch
181 * handlers for any asynchronous operations performed on the timer.
183 * @param expiry_time The expiry time to be used for the timer, relative to
186 basic_waitable_timer(boost::asio::io_service& io_service,
187 const duration& expiry_time)
188 : basic_io_object<WaitableTimerService>(io_service)
190 boost::system::error_code ec;
191 this->service.expires_from_now(this->implementation, expiry_time, ec);
192 boost::asio::detail::throw_error(ec, "expires_from_now");
195 /// Cancel any asynchronous operations that are waiting on the timer.
197 * This function forces the completion of any pending asynchronous wait
198 * operations against the timer. The handler for each cancelled operation will
199 * be invoked with the boost::asio::error::operation_aborted error code.
201 * Cancelling the timer does not change the expiry time.
203 * @return The number of asynchronous operations that were cancelled.
205 * @throws boost::system::system_error Thrown on failure.
207 * @note If the timer has already expired when cancel() is called, then the
208 * handlers for asynchronous wait operations will:
210 * @li have already been invoked; or
212 * @li have been queued for invocation in the near future.
214 * These handlers can no longer be cancelled, and therefore are passed an
215 * error code that indicates the successful completion of the wait operation.
219 boost::system::error_code ec;
220 std::size_t s = this->service.cancel(this->implementation, ec);
221 boost::asio::detail::throw_error(ec, "cancel");
225 /// Cancel any asynchronous operations that are waiting on the timer.
227 * This function forces the completion of any pending asynchronous wait
228 * operations against the timer. The handler for each cancelled operation will
229 * be invoked with the boost::asio::error::operation_aborted error code.
231 * Cancelling the timer does not change the expiry time.
233 * @param ec Set to indicate what error occurred, if any.
235 * @return The number of asynchronous operations that were cancelled.
237 * @note If the timer has already expired when cancel() is called, then the
238 * handlers for asynchronous wait operations will:
240 * @li have already been invoked; or
242 * @li have been queued for invocation in the near future.
244 * These handlers can no longer be cancelled, and therefore are passed an
245 * error code that indicates the successful completion of the wait operation.
247 std::size_t cancel(boost::system::error_code& ec)
249 return this->service.cancel(this->implementation, ec);
252 /// Cancels one asynchronous operation that is waiting on the timer.
254 * This function forces the completion of one pending asynchronous wait
255 * operation against the timer. Handlers are cancelled in FIFO order. The
256 * handler for the cancelled operation will be invoked with the
257 * boost::asio::error::operation_aborted error code.
259 * Cancelling the timer does not change the expiry time.
261 * @return The number of asynchronous operations that were cancelled. That is,
264 * @throws boost::system::system_error Thrown on failure.
266 * @note If the timer has already expired when cancel_one() is called, then
267 * the handlers for asynchronous wait operations will:
269 * @li have already been invoked; or
271 * @li have been queued for invocation in the near future.
273 * These handlers can no longer be cancelled, and therefore are passed an
274 * error code that indicates the successful completion of the wait operation.
276 std::size_t cancel_one()
278 boost::system::error_code ec;
279 std::size_t s = this->service.cancel_one(this->implementation, ec);
280 boost::asio::detail::throw_error(ec, "cancel_one");
284 /// Cancels one asynchronous operation that is waiting on the timer.
286 * This function forces the completion of one pending asynchronous wait
287 * operation against the timer. Handlers are cancelled in FIFO order. The
288 * handler for the cancelled operation will be invoked with the
289 * boost::asio::error::operation_aborted error code.
291 * Cancelling the timer does not change the expiry time.
293 * @param ec Set to indicate what error occurred, if any.
295 * @return The number of asynchronous operations that were cancelled. That is,
298 * @note If the timer has already expired when cancel_one() is called, then
299 * the handlers for asynchronous wait operations will:
301 * @li have already been invoked; or
303 * @li have been queued for invocation in the near future.
305 * These handlers can no longer be cancelled, and therefore are passed an
306 * error code that indicates the successful completion of the wait operation.
308 std::size_t cancel_one(boost::system::error_code& ec)
310 return this->service.cancel_one(this->implementation, ec);
313 /// Get the timer's expiry time as an absolute time.
315 * This function may be used to obtain the timer's current expiry time.
316 * Whether the timer has expired or not does not affect this value.
318 time_point expires_at() const
320 return this->service.expires_at(this->implementation);
323 /// Set the timer's expiry time as an absolute time.
325 * This function sets the expiry time. Any pending asynchronous wait
326 * operations will be cancelled. The handler for each cancelled operation will
327 * be invoked with the boost::asio::error::operation_aborted error code.
329 * @param expiry_time The expiry time to be used for the timer.
331 * @return The number of asynchronous operations that were cancelled.
333 * @throws boost::system::system_error Thrown on failure.
335 * @note If the timer has already expired when expires_at() is called, then
336 * the handlers for asynchronous wait operations will:
338 * @li have already been invoked; or
340 * @li have been queued for invocation in the near future.
342 * These handlers can no longer be cancelled, and therefore are passed an
343 * error code that indicates the successful completion of the wait operation.
345 std::size_t expires_at(const time_point& expiry_time)
347 boost::system::error_code ec;
348 std::size_t s = this->service.expires_at(
349 this->implementation, expiry_time, ec);
350 boost::asio::detail::throw_error(ec, "expires_at");
354 /// Set the timer's expiry time as an absolute time.
356 * This function sets the expiry time. Any pending asynchronous wait
357 * operations will be cancelled. The handler for each cancelled operation will
358 * be invoked with the boost::asio::error::operation_aborted error code.
360 * @param expiry_time The expiry time to be used for the timer.
362 * @param ec Set to indicate what error occurred, if any.
364 * @return The number of asynchronous operations that were cancelled.
366 * @note If the timer has already expired when expires_at() is called, then
367 * the handlers for asynchronous wait operations will:
369 * @li have already been invoked; or
371 * @li have been queued for invocation in the near future.
373 * These handlers can no longer be cancelled, and therefore are passed an
374 * error code that indicates the successful completion of the wait operation.
376 std::size_t expires_at(const time_point& expiry_time,
377 boost::system::error_code& ec)
379 return this->service.expires_at(this->implementation, expiry_time, ec);
382 /// Get the timer's expiry time relative to now.
384 * This function may be used to obtain the timer's current expiry time.
385 * Whether the timer has expired or not does not affect this value.
387 duration expires_from_now() const
389 return this->service.expires_from_now(this->implementation);
392 /// Set the timer's expiry time relative to now.
394 * This function sets the expiry time. Any pending asynchronous wait
395 * operations will be cancelled. The handler for each cancelled operation will
396 * be invoked with the boost::asio::error::operation_aborted error code.
398 * @param expiry_time The expiry time to be used for the timer.
400 * @return The number of asynchronous operations that were cancelled.
402 * @throws boost::system::system_error Thrown on failure.
404 * @note If the timer has already expired when expires_from_now() is called,
405 * then the handlers for asynchronous wait operations will:
407 * @li have already been invoked; or
409 * @li have been queued for invocation in the near future.
411 * These handlers can no longer be cancelled, and therefore are passed an
412 * error code that indicates the successful completion of the wait operation.
414 std::size_t expires_from_now(const duration& expiry_time)
416 boost::system::error_code ec;
417 std::size_t s = this->service.expires_from_now(
418 this->implementation, expiry_time, ec);
419 boost::asio::detail::throw_error(ec, "expires_from_now");
423 /// Set the timer's expiry time relative to now.
425 * This function sets the expiry time. Any pending asynchronous wait
426 * operations will be cancelled. The handler for each cancelled operation will
427 * be invoked with the boost::asio::error::operation_aborted error code.
429 * @param expiry_time The expiry time to be used for the timer.
431 * @param ec Set to indicate what error occurred, if any.
433 * @return The number of asynchronous operations that were cancelled.
435 * @note If the timer has already expired when expires_from_now() is called,
436 * then the handlers for asynchronous wait operations will:
438 * @li have already been invoked; or
440 * @li have been queued for invocation in the near future.
442 * These handlers can no longer be cancelled, and therefore are passed an
443 * error code that indicates the successful completion of the wait operation.
445 std::size_t expires_from_now(const duration& expiry_time,
446 boost::system::error_code& ec)
448 return this->service.expires_from_now(
449 this->implementation, expiry_time, ec);
452 /// Perform a blocking wait on the timer.
454 * This function is used to wait for the timer to expire. This function
455 * blocks and does not return until the timer has expired.
457 * @throws boost::system::system_error Thrown on failure.
461 boost::system::error_code ec;
462 this->service.wait(this->implementation, ec);
463 boost::asio::detail::throw_error(ec, "wait");
466 /// Perform a blocking wait on the timer.
468 * This function is used to wait for the timer to expire. This function
469 * blocks and does not return until the timer has expired.
471 * @param ec Set to indicate what error occurred, if any.
473 void wait(boost::system::error_code& ec)
475 this->service.wait(this->implementation, ec);
478 /// Start an asynchronous wait on the timer.
480 * This function may be used to initiate an asynchronous wait against the
481 * timer. It always returns immediately.
483 * For each call to async_wait(), the supplied handler will be called exactly
484 * once. The handler will be called when:
486 * @li The timer has expired.
488 * @li The timer was cancelled, in which case the handler is passed the error
489 * code boost::asio::error::operation_aborted.
491 * @param handler The handler to be called when the timer expires. Copies
492 * will be made of the handler as required. The function signature of the
494 * @code void handler(
495 * const boost::system::error_code& error // Result of operation.
497 * Regardless of whether the asynchronous operation completes immediately or
498 * not, the handler will not be invoked from within this function. Invocation
499 * of the handler will be performed in a manner equivalent to using
500 * boost::asio::io_service::post().
502 template <typename WaitHandler>
503 BOOST_ASIO_INITFN_RESULT_TYPE(WaitHandler,
504 void (boost::system::error_code))
505 async_wait(BOOST_ASIO_MOVE_ARG(WaitHandler) handler)
507 // If you get an error on the following line it means that your handler does
508 // not meet the documented type requirements for a WaitHandler.
509 BOOST_ASIO_WAIT_HANDLER_CHECK(WaitHandler, handler) type_check;
511 return this->service.async_wait(this->implementation,
512 BOOST_ASIO_MOVE_CAST(WaitHandler)(handler));
519 #include <boost/asio/detail/pop_options.hpp>
521 #endif // BOOST_ASIO_BASIC_WAITABLE_TIMER_HPP