// | |
// basic_deadline_timer.hpp | |
// ~~~~~~~~~~~~~~~~~~~~~~~~ | |
// | |
// Copyright (c) 2003-2011 Christopher M. Kohlhoff (chris at kohlhoff dot com) | |
// | |
// Distributed under the Boost Software License, Version 1.0. (See accompanying | |
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
// | |
#ifndef BOOST_ASIO_BASIC_DEADLINE_TIMER_HPP | |
#define BOOST_ASIO_BASIC_DEADLINE_TIMER_HPP | |
#if defined(_MSC_VER) && (_MSC_VER >= 1200) | |
# pragma once | |
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200) | |
#include <boost/asio/detail/config.hpp> | |
#include <cstddef> | |
#include <boost/asio/basic_io_object.hpp> | |
#include <boost/asio/deadline_timer_service.hpp> | |
#include <boost/asio/detail/throw_error.hpp> | |
#include <boost/asio/error.hpp> | |
#include <boost/asio/detail/push_options.hpp> | |
namespace boost { | |
namespace asio { | |
/// Provides waitable timer functionality. | |
/** | |
* The basic_deadline_timer class template provides the ability to perform a | |
* blocking or asynchronous wait for a timer to expire. | |
* | |
* A deadline timer is always in one of two states: "expired" or "not expired". | |
* If the wait() or async_wait() function is called on an expired timer, the | |
* wait operation will complete immediately. | |
* | |
* Most applications will use the boost::asio::deadline_timer typedef. | |
* | |
* @par Thread Safety | |
* @e Distinct @e objects: Safe.@n | |
* @e Shared @e objects: Unsafe. | |
* | |
* @par Examples | |
* Performing a blocking wait: | |
* @code | |
* // Construct a timer without setting an expiry time. | |
* boost::asio::deadline_timer timer(io_service); | |
* | |
* // Set an expiry time relative to now. | |
* timer.expires_from_now(boost::posix_time::seconds(5)); | |
* | |
* // Wait for the timer to expire. | |
* timer.wait(); | |
* @endcode | |
* | |
* @par | |
* Performing an asynchronous wait: | |
* @code | |
* void handler(const boost::system::error_code& error) | |
* { | |
* if (!error) | |
* { | |
* // Timer expired. | |
* } | |
* } | |
* | |
* ... | |
* | |
* // Construct a timer with an absolute expiry time. | |
* boost::asio::deadline_timer timer(io_service, | |
* boost::posix_time::time_from_string("2005-12-07 23:59:59.000")); | |
* | |
* // Start an asynchronous wait. | |
* timer.async_wait(handler); | |
* @endcode | |
* | |
* @par Changing an active deadline_timer's expiry time | |
* | |
* Changing the expiry time of a timer while there are pending asynchronous | |
* waits causes those wait operations to be cancelled. To ensure that the action | |
* associated with the timer is performed only once, use something like this: | |
* used: | |
* | |
* @code | |
* void on_some_event() | |
* { | |
* if (my_timer.expires_from_now(seconds(5)) > 0) | |
* { | |
* // We managed to cancel the timer. Start new asynchronous wait. | |
* my_timer.async_wait(on_timeout); | |
* } | |
* else | |
* { | |
* // Too late, timer has already expired! | |
* } | |
* } | |
* | |
* void on_timeout(const boost::system::error_code& e) | |
* { | |
* if (e != boost::asio::error::operation_aborted) | |
* { | |
* // Timer was not cancelled, take necessary action. | |
* } | |
* } | |
* @endcode | |
* | |
* @li The boost::asio::basic_deadline_timer::expires_from_now() function | |
* cancels any pending asynchronous waits, and returns the number of | |
* asynchronous waits that were cancelled. If it returns 0 then you were too | |
* late and the wait handler has already been executed, or will soon be | |
* executed. If it returns 1 then the wait handler was successfully cancelled. | |
* | |
* @li If a wait handler is cancelled, the boost::system::error_code passed to | |
* it contains the value boost::asio::error::operation_aborted. | |
*/ | |
template <typename Time, | |
typename TimeTraits = boost::asio::time_traits<Time>, | |
typename TimerService = deadline_timer_service<Time, TimeTraits> > | |
class basic_deadline_timer | |
: public basic_io_object<TimerService> | |
{ | |
public: | |
/// The time traits type. | |
typedef TimeTraits traits_type; | |
/// The time type. | |
typedef typename traits_type::time_type time_type; | |
/// The duration type. | |
typedef typename traits_type::duration_type duration_type; | |
/// Constructor. | |
/** | |
* This constructor creates a timer without setting an expiry time. The | |
* expires_at() or expires_from_now() functions must be called to set an | |
* expiry time before the timer can be waited on. | |
* | |
* @param io_service The io_service object that the timer will use to dispatch | |
* handlers for any asynchronous operations performed on the timer. | |
*/ | |
explicit basic_deadline_timer(boost::asio::io_service& io_service) | |
: basic_io_object<TimerService>(io_service) | |
{ | |
} | |
/// Constructor to set a particular expiry time as an absolute time. | |
/** | |
* This constructor creates a timer and sets the expiry time. | |
* | |
* @param io_service The io_service object that the timer will use to dispatch | |
* handlers for any asynchronous operations performed on the timer. | |
* | |
* @param expiry_time The expiry time to be used for the timer, expressed | |
* as an absolute time. | |
*/ | |
basic_deadline_timer(boost::asio::io_service& io_service, | |
const time_type& expiry_time) | |
: basic_io_object<TimerService>(io_service) | |
{ | |
boost::system::error_code ec; | |
this->service.expires_at(this->implementation, expiry_time, ec); | |
boost::asio::detail::throw_error(ec); | |
} | |
/// Constructor to set a particular expiry time relative to now. | |
/** | |
* This constructor creates a timer and sets the expiry time. | |
* | |
* @param io_service The io_service object that the timer will use to dispatch | |
* handlers for any asynchronous operations performed on the timer. | |
* | |
* @param expiry_time The expiry time to be used for the timer, relative to | |
* now. | |
*/ | |
basic_deadline_timer(boost::asio::io_service& io_service, | |
const duration_type& expiry_time) | |
: basic_io_object<TimerService>(io_service) | |
{ | |
boost::system::error_code ec; | |
this->service.expires_from_now(this->implementation, expiry_time, ec); | |
boost::asio::detail::throw_error(ec); | |
} | |
/// Cancel any asynchronous operations that are waiting on the timer. | |
/** | |
* This function forces the completion of any pending asynchronous wait | |
* operations against the timer. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* Cancelling the timer does not change the expiry time. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @throws boost::system::system_error Thrown on failure. | |
* | |
* @note If the timer has already expired when cancel() is called, then the | |
* handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t cancel() | |
{ | |
boost::system::error_code ec; | |
std::size_t s = this->service.cancel(this->implementation, ec); | |
boost::asio::detail::throw_error(ec); | |
return s; | |
} | |
/// Cancel any asynchronous operations that are waiting on the timer. | |
/** | |
* This function forces the completion of any pending asynchronous wait | |
* operations against the timer. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* Cancelling the timer does not change the expiry time. | |
* | |
* @param ec Set to indicate what error occurred, if any. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @note If the timer has already expired when cancel() is called, then the | |
* handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t cancel(boost::system::error_code& ec) | |
{ | |
return this->service.cancel(this->implementation, ec); | |
} | |
/// Get the timer's expiry time as an absolute time. | |
/** | |
* This function may be used to obtain the timer's current expiry time. | |
* Whether the timer has expired or not does not affect this value. | |
*/ | |
time_type expires_at() const | |
{ | |
return this->service.expires_at(this->implementation); | |
} | |
/// Set the timer's expiry time as an absolute time. | |
/** | |
* This function sets the expiry time. Any pending asynchronous wait | |
* operations will be cancelled. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* @param expiry_time The expiry time to be used for the timer. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @throws boost::system::system_error Thrown on failure. | |
* | |
* @note If the timer has already expired when expires_at() is called, then | |
* the handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t expires_at(const time_type& expiry_time) | |
{ | |
boost::system::error_code ec; | |
std::size_t s = this->service.expires_at( | |
this->implementation, expiry_time, ec); | |
boost::asio::detail::throw_error(ec); | |
return s; | |
} | |
/// Set the timer's expiry time as an absolute time. | |
/** | |
* This function sets the expiry time. Any pending asynchronous wait | |
* operations will be cancelled. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* @param expiry_time The expiry time to be used for the timer. | |
* | |
* @param ec Set to indicate what error occurred, if any. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @note If the timer has already expired when expires_at() is called, then | |
* the handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t expires_at(const time_type& expiry_time, | |
boost::system::error_code& ec) | |
{ | |
return this->service.expires_at(this->implementation, expiry_time, ec); | |
} | |
/// Get the timer's expiry time relative to now. | |
/** | |
* This function may be used to obtain the timer's current expiry time. | |
* Whether the timer has expired or not does not affect this value. | |
*/ | |
duration_type expires_from_now() const | |
{ | |
return this->service.expires_from_now(this->implementation); | |
} | |
/// Set the timer's expiry time relative to now. | |
/** | |
* This function sets the expiry time. Any pending asynchronous wait | |
* operations will be cancelled. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* @param expiry_time The expiry time to be used for the timer. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @throws boost::system::system_error Thrown on failure. | |
* | |
* @note If the timer has already expired when expires_from_now() is called, | |
* then the handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t expires_from_now(const duration_type& expiry_time) | |
{ | |
boost::system::error_code ec; | |
std::size_t s = this->service.expires_from_now( | |
this->implementation, expiry_time, ec); | |
boost::asio::detail::throw_error(ec); | |
return s; | |
} | |
/// Set the timer's expiry time relative to now. | |
/** | |
* This function sets the expiry time. Any pending asynchronous wait | |
* operations will be cancelled. The handler for each cancelled operation will | |
* be invoked with the boost::asio::error::operation_aborted error code. | |
* | |
* @param expiry_time The expiry time to be used for the timer. | |
* | |
* @param ec Set to indicate what error occurred, if any. | |
* | |
* @return The number of asynchronous operations that were cancelled. | |
* | |
* @note If the timer has already expired when expires_from_now() is called, | |
* then the handlers for asynchronous wait operations will: | |
* | |
* @li have already been invoked; or | |
* | |
* @li have been queued for invocation in the near future. | |
* | |
* These handlers can no longer be cancelled, and therefore are passed an | |
* error code that indicates the successful completion of the wait operation. | |
*/ | |
std::size_t expires_from_now(const duration_type& expiry_time, | |
boost::system::error_code& ec) | |
{ | |
return this->service.expires_from_now( | |
this->implementation, expiry_time, ec); | |
} | |
/// Perform a blocking wait on the timer. | |
/** | |
* This function is used to wait for the timer to expire. This function | |
* blocks and does not return until the timer has expired. | |
* | |
* @throws boost::system::system_error Thrown on failure. | |
*/ | |
void wait() | |
{ | |
boost::system::error_code ec; | |
this->service.wait(this->implementation, ec); | |
boost::asio::detail::throw_error(ec); | |
} | |
/// Perform a blocking wait on the timer. | |
/** | |
* This function is used to wait for the timer to expire. This function | |
* blocks and does not return until the timer has expired. | |
* | |
* @param ec Set to indicate what error occurred, if any. | |
*/ | |
void wait(boost::system::error_code& ec) | |
{ | |
this->service.wait(this->implementation, ec); | |
} | |
/// Start an asynchronous wait on the timer. | |
/** | |
* This function may be used to initiate an asynchronous wait against the | |
* timer. It always returns immediately. | |
* | |
* For each call to async_wait(), the supplied handler will be called exactly | |
* once. The handler will be called when: | |
* | |
* @li The timer has expired. | |
* | |
* @li The timer was cancelled, in which case the handler is passed the error | |
* code boost::asio::error::operation_aborted. | |
* | |
* @param handler The handler to be called when the timer expires. Copies | |
* will be made of the handler as required. The function signature of the | |
* handler must be: | |
* @code void handler( | |
* const boost::system::error_code& error // Result of operation. | |
* ); @endcode | |
* Regardless of whether the asynchronous operation completes immediately or | |
* not, the handler will not be invoked from within this function. Invocation | |
* of the handler will be performed in a manner equivalent to using | |
* boost::asio::io_service::post(). | |
*/ | |
template <typename WaitHandler> | |
void async_wait(WaitHandler handler) | |
{ | |
this->service.async_wait(this->implementation, handler); | |
} | |
}; | |
} // namespace asio | |
} // namespace boost | |
#include <boost/asio/detail/pop_options.hpp> | |
#endif // BOOST_ASIO_BASIC_DEADLINE_TIMER_HPP |