| Home | Libraries | People | FAQ | More

# boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service > Class Template Reference

Inherits boost::asio::basic_io_object< Service >< Service >.

Inheritance diagram for boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >:

List of all members.

## Detailed Description

### template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>
class boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >

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.

Most applications will use the boost::asio::deadline_timer typedef.

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

Concepts:
  Async_Object, Error_Source.

See also:
  Changing an active deadline_timer's expiry time

Examples:
  Performing a blocking wait:

       // 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();

  Performing an asynchronous wait:

       void handler(const boost::asio::error& 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);

## Public Types

typedef boost::asio::error | error_type
| The type used for reporting errors.
typedef Time_Traits | traits_type
| The time traits type.
typedef traits_type::time_type | time_type
| The time type.
typedef traits_type::duration_type | duration_type
| The duration type.
typedef Service | service_type
| The type of the service that will be used to provide I/O operations.
typedef service_type::implementation_type | implementation_type
| The underlying implementation type of I/O object.

## Public Member Functions

| basic_deadline_timer (boost::asio::io_service &io_service)
| Constructor.
| basic_deadline_timer (boost::asio::io_service &io_service, const time_type &expiry_time)
| Constructor to set a particular expiry time as an absolute time.
| basic_deadline_timer (boost::asio::io_service &io_service, const duration_type &expiry_time)
| Constructor to set a particular expiry time relative to now.
std::size_t | cancel ()
| Cancel any asynchronous operations that are waiting on the timer.
time_type | expires_at () const
| Get the timer's expiry time as an absolute time.
std::size_t | expires_at (const time_type &expiry_time)
| Set the timer's expiry time as an absolute time.
duration_type | expires_from_now () const
| Get the timer's expiry time relative to now.
std::size_t | expires_from_now (const duration_type &expiry_time)
| Set the timer's expiry time relative to now.
void | wait ()
| Perform a blocking wait on the timer.
template<typename Handler>
void | async_wait (Handler handler)
| Start an asynchronous wait on the timer.
boost::asio::io_service & | io_service ()
| Get the io_service associated with the object.

## Member Typedef Documentation

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

typedef boost::asio::error boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::error_type

The type used for reporting errors.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

typedef Time_Traits boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::traits_type

The time traits type.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

typedef traits_type::time_type boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::time_type

The time type.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

typedef traits_type::duration_type boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::duration_type

The duration type.

template<typename Service>

typedef Service boost::asio::basic_io_object< Service >::service_type `[inherited]`

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

template<typename Service>

typedef service_type::implementation_type boost::asio::basic_io_object< Service >::implementation_type `[inherited]`

The underlying implementation type of I/O object.

## Constructor & Destructor Documentation

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::basic_deadline_timer | ( | boost::asio::io_service & | io_service | ) | `[explicit]`

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 Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::basic_deadline_timer | ( | boost::asio::io_service & | io_service,
|  | const time_type & | expiry_time |
| ) |  |  |

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.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::basic_deadline_timer | ( | boost::asio::io_service & | io_service,
|  | const duration_type & | expiry_time |
| ) |  |  |

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.

## Member Function Documentation

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

std::size_t boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::cancel | ( |  | ) |

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.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

time_type boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::expires_at | ( |  | ) | const

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.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

std::size_t boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::expires_at | ( | const time_type & | expiry_time | ) |

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.

See Changing an active deadline_timer's expiry time for more information on altering the expiry time of an active timer.

Parameters:

  | expiry_time | The expiry time to be used for the timer.

Returns:
  The number of asynchronous operations that were cancelled.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

duration_type boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::expires_from_now | ( |  | ) | const

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.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

std::size_t boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::expires_from_now | ( | const duration_type & | expiry_time | ) |

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.

See Changing an active deadline_timer's expiry time for more information on altering the expiry time of an active timer.

Parameters:

  | expiry_time | The expiry time to be used for the timer.

Returns:
  The number of asynchronous operations that were cancelled.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>

void boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::wait | ( |  | ) |

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::asio::error | Thrown on failure.

template<typename Time_Type, typename Time_Traits = boost::asio::time_traits<Time_Type>, typename Service = deadline_timer_service<Time_Type, Time_Traits>>
template<typename Handler>

void boost::asio::basic_deadline_timer< Time_Type, Time_Traits, Service >::async_wait | ( | Handler | handler | ) |

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::asio::error& 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().

template<typename Service>

boost::asio::io_service& boost::asio::basic_io_object< Service >::io_service | ( |  | ) | `[inherited]`

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.

| Copyright © 2003 - 2006 Christopher M. Kohlhoff