15 Timers [timer]

15.4 Class template basic_waitable_timer [timer.waitable]

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class Clock, class WaitTraits = wait_traits<Clock>>
  class basic_waitable_timer
  {
  public:
    // types:

    using executor_type = io_context::executor_type;
    using clock_type = Clock;
    using duration = typename clock_type::duration;
    using time_point = typename clock_type::time_point;
    using traits_type = WaitTraits;

    // [timer.waitable.cons], construct / copy / destroy:

    explicit basic_waitable_timer(io_context& ctx);
    basic_waitable_timer(io_context& ctx, const time_point& t);
    basic_waitable_timer(io_context& ctx, const duration& d);
    basic_waitable_timer(const basic_waitable_timer&) = delete;
    basic_waitable_timer(basic_waitable_timer&& rhs);

    ~basic_waitable_timer();

    basic_waitable_timer& operator=(const basic_waitable_timer&) = delete;
    basic_waitable_timer& operator=(basic_waitable_timer&& rhs);

    // [timer.waitable.ops], basic_waitable_timer operations:

    executor_type get_executor() noexcept;

    size_t cancel();
    size_t cancel_one();

    time_point expiry() const;
    size_t expires_at(const time_point& t);
    size_t expires_after(const duration& d);

    void wait();
    void wait(error_code& ec);

    template<class CompletionToken>
      DEDUCED async_wait(CompletionToken&& token);
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Instances of class template basic_waitable_timer meet the requirements of Destructible (C++ 2014 [destructible]), MoveConstructible (C++ 2014 [moveconstructible]), and MoveAssignable (C++ 2014 [moveassignable]).

15.4.1 basic_waitable_timer constructors [timer.waitable.cons]

explicit basic_waitable_timer(io_context& ctx);

Effects: Equivalent to basic_waitable_timer(ctx, time_point()).

basic_waitable_timer(io_context& ctx, const time_point& t);

Postconditions:

  • get_executor() == ctx.get_executor().

  • expiry() == t.

basic_waitable_timer(io_context& ctx, const duration& d);

Effects: Sets the expiry time as if by calling expires_after(d).

Postconditions: get_executor() == ctx.get_executor().

basic_waitable_timer(basic_waitable_timer&& rhs);

Effects: Move constructs an object of class basic_waitable_timer<Clock, WaitTraits> that refers to the state originally represented by rhs.

Postconditions:

  • get_executor() == rhs.get_executor().

  • expiry() returns the same value as rhs.expiry() prior to the constructor invocation.

  • rhs.expiry() == time_point().

15.4.2 basic_waitable_timer destructor [timer.waitable.dtor]

~basic_waitable_timer();

Effects: Destroys the timer, canceling any asynchronous wait operations associated with the timer as if by calling cancel().

15.4.3 basic_waitable_timer assignment [timer.waitable.assign]

basic_waitable_timer& operator=(basic_waitable_timer&& rhs);

Effects: Cancels any outstanding asynchronous operations associated with *this as if by calling cancel(), then moves into *this the state originally represented by rhs.

Postconditions:

  • get_executor() == rhs.get_executor().

  • expiry() returns the same value as rhs.expiry() prior to the assignment.

  • rhs.expiry() == time_point().

Returns: *this.

15.4.4 basic_waitable_timer operations [timer.waitable.ops]

executor_type get_executor() noexcept;

Returns: The associated executor.

size_t cancel();

Effects: Causes any outstanding asynchronous wait operations to complete. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true.

Returns: The number of operations that were canceled.

Remarks: Does not block (C++ 2014 [defns.block]) the calling thread pending completion of the canceled operations.

size_t cancel_one();

Effects: Causes the outstanding asynchronous wait operation that was initiated first, if any, to complete as soon as possible. The completion handler for the canceled operation is passed an error code ec such that ec == errc::operation_canceled yields true.

Returns: 1 if an operation was canceled, otherwise 0.

Remarks: Does not block (C++ 2014 [defns.block]) the calling thread pending completion of the canceled operation.

time_point expiry() const;

Returns: The expiry time associated with the timer, as previously set using expires_at() or expires_after().

size_t expires_at(const time_point& t);

Effects: Cancels outstanding asynchronous wait operations, as if by calling cancel(). Sets the expiry time associated with the timer.

Returns: The number of operations that were canceled.

Postconditions: expiry() == t.

size_t expires_after(const duration& d);

Returns: expires_at(clock_type::now() + d).

void wait(); void wait(error_code& ec);

Effects: Establishes the postcondition as if by repeatedly blocking the calling thread (C++ 2014 [defns.block]) for the relative time produced by WaitTraits::to_wait_duration(expiry()).

Postconditions: ec || expiry() <= clock_type::now().

template<class CompletionToken> DEDUCED async_wait(CompletionToken&& token);

Completion signature: void(error_code ec).

Effects: Initiates an asynchronous wait operation to repeatedly wait for the relative time produced by WaitTraits::to_wait_duration(e), where e is a value of type time_point such that e <= expiry(). The completion handler is submitted for execution only when the condition ec || expiry() <= clock_type::now() yields true.

Note: To implement async_wait, an io_context object ctx could maintain a priority queue for each specialization of basic_waitable_timer<Clock, WaitTraits> for which a timer object was initialized with ctx. Only the time point e of the earliest outstanding expiry need be passed to WaitTraits::to_wait_duration(e).  — end note ]