Provides waitable timer functionality. More...

#include <basic_waitable_timer.hpp>

Inheritance diagram for boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >:

Collaboration diagram for boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >:

Public Types
typedef Clock	clock_type
	The clock type. More...

typedef clock_type::duration	duration
	The duration type of the clock. More...

typedef clock_type::time_point	time_point
	The time point type of the clock. More...

typedef WaitTraits	traits_type
	The wait traits type. More...

typedef WaitableTimerService	service_type
	The type of the service that will be used to provide I/O operations. More...

typedef service_type::implementation_type	implementation_type
	The underlying implementation type of I/O object. More...

Public Member Functions
	basic_waitable_timer (boost::asio::io_service &io_service)
	Constructor. More...

	basic_waitable_timer (boost::asio::io_service &io_service, const time_point &expiry_time)
	Constructor to set a particular expiry time as an absolute time. More...

	basic_waitable_timer (boost::asio::io_service &io_service, const duration &expiry_time)
	Constructor to set a particular expiry time relative to now. More...

std::size_t	cancel ()
	Cancel any asynchronous operations that are waiting on the timer. More...

std::size_t	cancel (boost::system::error_code &ec)
	Cancel any asynchronous operations that are waiting on the timer. More...

std::size_t	cancel_one ()
	Cancels one asynchronous operation that is waiting on the timer. More...

std::size_t	cancel_one (boost::system::error_code &ec)
	Cancels one asynchronous operation that is waiting on the timer. More...

time_point	expires_at () const
	Get the timer's expiry time as an absolute time. More...

std::size_t	expires_at (const time_point &expiry_time)
	Set the timer's expiry time as an absolute time. More...

std::size_t	expires_at (const time_point &expiry_time, boost::system::error_code &ec)
	Set the timer's expiry time as an absolute time. More...

duration	expires_from_now () const
	Get the timer's expiry time relative to now. More...

std::size_t	expires_from_now (const duration &expiry_time)
	Set the timer's expiry time relative to now. More...

std::size_t	expires_from_now (const duration &expiry_time, boost::system::error_code &ec)
	Set the timer's expiry time relative to now. More...

void	wait ()
	Perform a blocking wait on the timer. More...

void	wait (boost::system::error_code &ec)
	Perform a blocking wait on the timer. More...

template<typename WaitHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (WaitHandler, void(boost::system::error_code)) async_wait(BOOST_ASIO_MOVE_ARG(WaitHandler) handler)
	Start an asynchronous wait on the timer. More...

boost::asio::io_service &	get_io_service ()
	Get the io_service associated with the object. More...

Protected Member Functions
service_type &	get_service ()
	Get the service associated with the I/O object. More...

const service_type &	get_service () const
	Get the service associated with the I/O object. More...

implementation_type &	get_implementation ()
	Get the underlying implementation of the I/O object. More...

const implementation_type &	get_implementation () const
	Get the underlying implementation of the I/O object. More...

Protected Attributes
service_type &	service
	(Deprecated: Use get_service().) The service associated with the I/O object. More...

implementation_type	implementation
	(Deprecated: Use get_implementation().) The underlying implementation of the I/O object. More...

Detailed Description

template<typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>
class boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >

Provides waitable timer functionality.

The basic_waitable_timer class template provides the ability to perform a blocking or asynchronous wait for a timer to expire.

A waitable 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 one of the boost::asio::steady_timer, boost::asio::system_timer or boost::asio::high_resolution_timer typedefs.

Note: This waitable timer functionality is for use with the C++11 standard library's <chrono> facility, or with the Boost.Chrono library.

Thread Safety: Distinct objects: Safe.
Shared objects: Unsafe.

Examples: Performing a blocking wait (C++11):
// Construct a timer without setting an expiry time.

boost::asio::steady_timer timer(io_service);

// Set an expiry time relative to now.

timer.expires_from_now(std::chrono::seconds(5));

// Wait for the timer to expire.

timer.wait();

: Performing an asynchronous wait (C++11):
void handler(const boost::system::error_code& error)

{

if (!error)

{

// Timer expired.

}

}

...

// Construct a timer with an absolute expiry time.

boost::asio::steady_timer timer(io_service,

std::chrono::steady_clock::now() + std::chrono::seconds(60));

// Start an asynchronous wait.

timer.async_wait(handler);

Changing an active waitable 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:

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.
  }
}

The boost::asio::basic_waitable_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.

If a wait handler is cancelled, the boost::system::error_code passed to it contains the value boost::asio::error::operation_aborted.

Member Typedef Documentation

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

typedef Clock boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::clock_type

The clock type.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

typedef clock_type::duration boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::duration

The duration type of the clock.

typedef service_type::implementation_type boost::asio::basic_io_object< WaitableTimerService >::implementation_type

inherited

The underlying implementation type of I/O object.

typedef WaitableTimerService boost::asio::basic_io_object< WaitableTimerService >::service_type

inherited

The type of the service that will be used to provide I/O operations.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

typedef clock_type::time_point boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::time_point

The time point type of the clock.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

typedef WaitTraits boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::traits_type

The wait traits type.

Constructor & Destructor Documentation

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::basic_waitable_timer ( boost::asio::io_service & io_service )

inlineexplicit

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.

Parameters

io_service The io_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::basic_waitable_timer	(	boost::asio::io_service &	io_service,
		const time_point &	expiry_time
	)

inline

Constructor to set a particular expiry time as an absolute time.

This constructor creates a timer and sets the expiry time.

Parameters

io_service	The io_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer.
expiry_time	The expiry time to be used for the timer, expressed as an absolute time.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::basic_waitable_timer	(	boost::asio::io_service &	io_service,
		const duration &	expiry_time
	)

inline

Constructor to set a particular expiry time relative to now.

This constructor creates a timer and sets the expiry time.

Parameters

io_service	The io_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer.
expiry_time	The expiry time to be used for the timer, relative to now.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

Member Function Documentation

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

template<typename WaitHandler >

boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::BOOST_ASIO_INITFN_RESULT_TYPE	(	WaitHandler	,
		void(boost::system::error_code)
	)

inline

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:

The timer has expired.

The timer was cancelled, in which case the handler is passed the error code boost::asio::error::operation_aborted.

Parameters

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:

 void handler(
  const boost::system::error_code& error // Result of operation.
); 

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().

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::cancel ( )

inline

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.

Returns: The number of asynchronous operations that were cancelled.

Exceptions

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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, boost::asio::s, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::cancel ( boost::system::error_code & ec )

inline

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.

Parameters

ec	Set to indicate what error occurred, if any.

Returns: 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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::cancel_one ( )

inline

Cancels one asynchronous operation that is waiting on the timer.

This function forces the completion of one pending asynchronous wait operation against the timer. Handlers are cancelled in FIFO order. The handler for the cancelled operation will be invoked with the boost::asio::error::operation_aborted error code.

Cancelling the timer does not change the expiry time.

Returns: The number of asynchronous operations that were cancelled. That is, either 0 or 1.

Exceptions

boost::system::system_error Thrown on failure.

Note: If the timer has already expired when cancel_one() is called, then the handlers for asynchronous wait operations will:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, boost::asio::s, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::cancel_one ( boost::system::error_code & ec )

inline

Cancels one asynchronous operation that is waiting on the timer.

This function forces the completion of one pending asynchronous wait operation against the timer. Handlers are cancelled in FIFO order. The handler for the cancelled operation will be invoked with the boost::asio::error::operation_aborted error code.

Cancelling the timer does not change the expiry time.

Parameters

ec	Set to indicate what error occurred, if any.

Returns: The number of asynchronous operations that were cancelled. That is, either 0 or 1.

Note: If the timer has already expired when cancel_one() is called, then the handlers for asynchronous wait operations will:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

time_point boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_at ( ) const

inline

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_at ( const time_point & expiry_time )

inline

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.

Parameters

expiry_time The expiry time to be used for the timer.

Returns: The number of asynchronous operations that were cancelled.

Exceptions

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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, boost::asio::s, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_at	(	const time_point &	expiry_time,
		boost::system::error_code &	ec
	)

inline

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.

Parameters

expiry_time	The expiry time to be used for the timer.
ec	Set to indicate what error occurred, if any.

Returns: 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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

duration boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_from_now ( ) const

inline

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_from_now ( const duration & expiry_time )

inline

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.

Parameters

expiry_time The expiry time to be used for the timer.

Returns: The number of asynchronous operations that were cancelled.

Exceptions

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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, boost::asio::s, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

std::size_t boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::expires_from_now	(	const duration &	expiry_time,
		boost::system::error_code &	ec
	)

inline

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.

Parameters

expiry_time	The expiry time to be used for the timer.
ec	Set to indicate what error occurred, if any.

Returns: 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:

have already been invoked; or

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.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

implementation_type& boost::asio::basic_io_object< WaitableTimerService >::get_implementation ( )

inlineprotectedinherited

Get the underlying implementation of the I/O object.

const implementation_type& boost::asio::basic_io_object< WaitableTimerService >::get_implementation ( ) const

inlineprotectedinherited

Get the underlying implementation of the I/O object.

boost::asio::io_service& boost::asio::basic_io_object< WaitableTimerService >::get_io_service ( )

inlineinherited

Get the io_service associated with the object.

This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.

Returns: A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.

service_type& boost::asio::basic_io_object< WaitableTimerService >::get_service ( )

inlineprotectedinherited

Get the service associated with the I/O object.

const service_type& boost::asio::basic_io_object< WaitableTimerService >::get_service ( ) const

inlineprotectedinherited

Get the service associated with the I/O object.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

void boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::wait ( )

inline

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.

Exceptions

boost::system::system_error Thrown on failure.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

template<typename Clock , typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>

void boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >::wait ( boost::system::error_code & ec )

inline

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.

Parameters

ec	Set to indicate what error occurred, if any.

References boost::asio::basic_io_object< WaitableTimerService >::implementation, and boost::asio::basic_io_object< WaitableTimerService >::service.

Member Data Documentation

implementation_type boost::asio::basic_io_object< WaitableTimerService >::implementation

protectedinherited

(Deprecated: Use get_implementation().) The underlying implementation of the I/O object.

service_type& boost::asio::basic_io_object< WaitableTimerService >::service

protectedinherited

(Deprecated: Use get_service().) The service associated with the I/O object.

Note: Available only for services that do not support movability.

The documentation for this class was generated from the following file:

boost_1_57_0/boost/asio/basic_waitable_timer.hpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

template<typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>> class boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>>
class boost::asio::basic_waitable_timer< Clock, WaitTraits, WaitableTimerService >