Time

Overview

Interacting with time, timers, and timeouts.

Learn more: Interacting with time, timers, and timeouts

Classes
struct	pw::async2::EmptyReadyResolution
struct	pw::async2::ReadyFunctionResultResolution< T >
struct	pw::async2::ReadyConstantValueResolution< T, ConstantType, CastType >
class	pw::async2::FutureWithTimeout< T, PrimaryFuture, TimeoutFuture, TimeoutResolution, typename, typename, typename >
class	pw::async2::SimulatedTimeProvider< Clock >
	A simulated TimeProvider suitable for testing APIs which use Timer. More...
class	pw::async2::TimeFuture< Clock >
class	pw::async2::TimeProvider< Clock >

Typedefs
template<typename T >
using	pw::async2::DeadlineExceededResolution = ReadyConstantValueResolution< T, std::integral_constant< pw::Status::Code, PW_STATUS_DEADLINE_EXCEEDED >, pw::Status >
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::ValueFutureWithTimeout = decltype(Timeout(std::declval< ValueFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename U , typename Clock = chrono::SystemClock>
using	pw::async2::ValueFutureWithTimeoutOr = decltype(TimeoutOr(std::declval< ValueFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >(), std::declval< U && >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::SendFutureWithTimeout = decltype(Timeout(std::declval< SendFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::ReceiveFutureWithTimeout = decltype(Timeout(std::declval< ReceiveFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::ReserveSendFutureWithTimeout = decltype(Timeout(std::declval< ReserveSendFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::SendFutureWithTimeoutOrClosed = decltype(TimeoutOrClosed(std::declval< SendFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::ReceiveFutureWithTimeoutOrClosed = decltype(TimeoutOrClosed(std::declval< ReceiveFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename T , typename Clock = chrono::SystemClock>
using	pw::async2::ReserveSendFutureWithTimeoutOrClosed = decltype(TimeoutOrClosed(std::declval< ReserveSendFuture< T > && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename FutureType , typename Clock = chrono::SystemClock>
using	pw::async2::CustomFutureWithTimeout = decltype(Timeout(std::declval< FutureType && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >()))
template<typename FutureType , typename U , typename Clock = chrono::SystemClock>
using	pw::async2::CustomFutureWithTimeoutOr = decltype(TimeoutOr(std::declval< FutureType && >(), std::declval< TimeProvider< Clock > & >(), std::declval< typename Clock::duration >(), std::declval< U && >()))

Functions
template<typename T , typename PrimaryFuture , typename TimeoutFuture , typename TimeoutResolution >
auto	pw::async2::CreateFutureWithTimeout (PrimaryFuture &&primary_future, TimeoutFuture &&timeout_future, TimeoutResolution &&timeout_resolution) -> FutureWithTimeout< T, std::decay_t< PrimaryFuture >, std::decay_t< TimeoutFuture >, std::decay_t< TimeoutResolution > >
template<typename PrimaryFuture , typename TimeProvider , typename Duration , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>
auto	pw::async2::Timeout (PrimaryFuture &&primary_future, TimeProvider &time_provider, Duration delay)
template<typename PrimaryFuture , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>
auto	pw::async2::Timeout (PrimaryFuture &&primary_future, typename chrono::SystemClock::duration delay)
template<typename Clock >
void	pw::async2::TimeoutOr (ValueFuture< void > &&future, TimeProvider< Clock > &time_provider, typename Clock::duration delay)
template<typename PrimaryFuture , typename Clock , typename U >
auto	pw::async2::TimeoutOr (PrimaryFuture &&primary_future, TimeProvider< Clock > &time_provider, typename Clock::duration delay, U &&value_or_fn_on_timeout)
template<typename PrimaryFuture , typename... Args, int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>
auto	pw::async2::TimeoutOr (PrimaryFuture &&primary_future, typename chrono::SystemClock::duration delay, Args &&... args)
template<typename T , typename Clock >
auto	pw::async2::TimeoutOrClosed (ReceiveFuture< T > &&future, TimeProvider< Clock > &time_provider, typename Clock::duration delay)
template<typename T , typename Clock >
auto	pw::async2::TimeoutOrClosed (SendFuture< T > &&future, TimeProvider< Clock > &time_provider, typename Clock::duration delay)
template<typename T , typename Clock >
auto	pw::async2::TimeoutOrClosed (ReserveSendFuture< T > &&future, TimeProvider< Clock > &time_provider, typename Clock::duration delay)
template<typename PrimaryFuture , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>
auto	pw::async2::TimeoutOrClosed (PrimaryFuture &&primary_future, typename chrono::SystemClock::duration delay)
TimeProvider< chrono::SystemClock > &	pw::async2::GetSystemTimeProvider ()
	Returns a TimeProvider using the "real" SystemClock and SystemTimer.
void	pw::async2::TimeProvider< Clock >::RunExpired (typename Clock::time_point now)

Typedef Documentation

CustomFutureWithTimeout

template<typename FutureType , typename Clock = chrono::SystemClock>

using pw::async2::CustomFutureWithTimeout = typedef decltype(Timeout(std::declval<FutureType&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

CustomFutureWithTimeout<FutureType> is an alias for the type you get if you invoke Timeout() with a FutureType, to generate a composite future with a timeout.

CustomFutureWithTimeoutOr

template<typename FutureType , typename U , typename Clock = chrono::SystemClock>

using pw::async2::CustomFutureWithTimeoutOr = typedef decltype(TimeoutOr(std::declval<FutureType&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>(), std::declval<U&&>()))

CustomFutureWithTimeoutOr<FutureType, U> is an alias for the type you get if you invoke TimeoutOr(..., U&&) with FutureType, to generate a composite future with a timeout.

U is either the sentinel value type if you specify a constant value, or Function<T()> if you use a function to generate the sentinel value.

DeadlineExceededResolution

template<typename T >

using pw::async2::DeadlineExceededResolution = typedef ReadyConstantValueResolution< T, std::integral_constant<pw::Status::Code, PW_STATUS_DEADLINE_EXCEEDED>, pw::Status>

When used as the TimeoutResolution type parameter, causes the FutureWithTimeout wrapper to return a Status.DeadlineExceeded() value when there is a timeout. Usually this is is used in a way that modifies the Poll<U> type to instead use Poll<Result<T>>, so that the error state is distinct from a non-timeout value.

ReceiveFutureWithTimeout

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::ReceiveFutureWithTimeout = typedef decltype(Timeout(std::declval<ReceiveFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

ReceiveFutureWithTimeout<T> is an alias for the type you get if you invoke Timeout() with ReceiveFuture<T> as the future to add a timeout to.

ReceiveFutureWithTimeoutOrClosed

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::ReceiveFutureWithTimeoutOrClosed = typedef decltype(TimeoutOrClosed(std::declval<ReceiveFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

ReceiveFutureWithTimeoutOrClosed<T> is an alias for the type you get if you invoke TimeoutOrClosed() with ReceiveFuture<T> as the future to add a timeout to.

ReserveSendFutureWithTimeout

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::ReserveSendFutureWithTimeout = typedef decltype(Timeout(std::declval<ReserveSendFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

ReserveSendFutureWithTimeout<T> is an alias for the type you get if you invoke Timeout() with ReserveSendFuture<T> as the future to add a timeout to.

ReserveSendFutureWithTimeoutOrClosed

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::ReserveSendFutureWithTimeoutOrClosed = typedef decltype(TimeoutOrClosed(std::declval<ReserveSendFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

ReserveSendFutureWithTimeoutOrClosed<T> is an alias for the type you get if you invoke TimeoutOrClosed() with ReserveSendFuture<T> as the future to add a timeout to.

SendFutureWithTimeout

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::SendFutureWithTimeout = typedef decltype(Timeout(std::declval<SendFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

SendFutureWithTimeout<T> is an alias for the type you get if you invoke Timeout() with SendFuture<T> as the future to add a timeout to.

SendFutureWithTimeoutOrClosed

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::SendFutureWithTimeoutOrClosed = typedef decltype(TimeoutOrClosed(std::declval<SendFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

SendFutureWithTimeoutOrClosed<T> is an alias for the type you get if you invoke TimeoutOrClosed() with SendFuture<T> as the future to add a timeout to.

ValueFutureWithTimeout

template<typename T , typename Clock = chrono::SystemClock>

using pw::async2::ValueFutureWithTimeout = typedef decltype(Timeout(std::declval<ValueFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>()))

ValueFutureWithTimeout<T> is an alias for the type you get if you invoke Timeout() with ValueFuture<T> as the future to add a timeout to.

ValueFutureWithTimeoutOr

template<typename T , typename U , typename Clock = chrono::SystemClock>

using pw::async2::ValueFutureWithTimeoutOr = typedef decltype(TimeoutOr(std::declval<ValueFuture<T>&&>(), std::declval<TimeProvider<Clock>&>(), std::declval<typename Clock::duration>(), std::declval<U&&>()))

ValueFutureWithTimeoutOr<T, U> is an alias for the type you get if you invoke TimeoutOr(..., U&&) with ValueFuture<T> as the future to add a timeout to.

U is either the sentinel value type if you specify a constant value, or Function<T()> if you use a function to generate the sentinel value.

Function Documentation

CreateFutureWithTimeout()

template<typename T , typename PrimaryFuture , typename TimeoutFuture , typename TimeoutResolution >

auto pw::async2::CreateFutureWithTimeout	(	PrimaryFuture &&	primary_future,
		TimeoutFuture &&	timeout_future,
		TimeoutResolution &&	timeout_resolution
	)		-> FutureWithTimeout<T, std::decay_t<PrimaryFuture>, std::decay_t<TimeoutFuture>, std::decay_t<TimeoutResolution>>

Helper class to construct a FutureWithTimeout instance given the value type T along with the types and values which are the components for that future.

It effectively acts as a class template deduction guide, where all the type parameters are deduced except for the first T type parameter. This sort of partial deduction is not possible with CTAD.

RunExpired()

template<typename Clock >

void pw::async2::TimeProvider< Clock >::RunExpired ( typename Clock::time_point  now )

protected

Run all expired timers with the current (provided) time_point.

This method should be invoked by subclasses when DoInvokeAt's timer expires.

Timeout() [1/2]

template<typename PrimaryFuture , typename TimeProvider , typename Duration , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>

auto pw::async2::Timeout	(	PrimaryFuture &&	primary_future,
		TimeProvider &	time_provider,
		Duration	delay
	)

Creates a future, resolving to a pw::Result<T> wrapping an existing future that resolves to a T.

If the given future completes before the timeout, the Result-wrapped value is returned. If however the timeout occurs, the returned status matches status.IsDeadlineExceed().

The timeout is based on the given time provider, using whatever clock source backs it. The timeout period begins when this call is made, and ends when the time provider decides that the given delay has passed.

Timeout() [2/2]

template<typename PrimaryFuture , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>

auto pw::async2::Timeout	(	PrimaryFuture &&	primary_future,
		typename chrono::SystemClock::duration	delay
	)

Creates a future, resolving to a pw::Result<T> wrapping an existing future that resolves to a T.

If the given future completes before the timeout, the Result-wrapped value is returned. If however the timeout occurs, the returned status matches status.IsDeadlineExceed().

This overload uses GetSystemTimeProvider() to get the system clock time provider for the timeouts. The timeout period begins when this call is made, and ends when the given amount of time has passed according to the system clock.

TimeoutOr() [1/3]

template<typename PrimaryFuture , typename Clock , typename U >

auto pw::async2::TimeoutOr	(	PrimaryFuture &&	primary_future,
		TimeProvider< Clock > &	time_provider,
		typename Clock::duration	delay,
		U &&	value_or_fn_on_timeout
	)

Constructs a FutureWithTimeout for a ValueFuture<T> as the primary future, a timeout future obtained from a TimeProvider<Clock> instance, and the timeout delay.

On timeout, the value_or_fn_on_timeout function is used to obtain a sentinel value to return as the Ready(T) from the composed future's Pend(), either by invoking it with no arguments if it is a function, or by converting it to the T type.

Note that sentinel values can be problematic. You should generally prefer to use the non-sentinel call Timeout(...) which results in a value with a status code you can check.

TimeoutOr() [2/3]

template<typename PrimaryFuture , typename... Args, int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>

auto pw::async2::TimeoutOr	(	PrimaryFuture &&	primary_future,
		typename chrono::SystemClock::duration	delay,
		Args &&...	args
	)

Helper function for using one of the other TimeoutOr overloads which take a TimeProvider.

This overload uses the system time provider returned by the call to GetSystemTimeProvider(), and forwards it as the time provider along with the other arguments to the other overloads. See those other overloads to understand what type of future you will construct.

TimeoutOr() [3/3]

template<typename Clock >

void pw::async2::TimeoutOr	(	ValueFuture< void > &&	future,
		TimeProvider< Clock > &	time_provider,
		typename Clock::duration	delay
	)

Constructs a FutureWithTimeout for a ValueFuture<void> as the primary future, a timeout future obtained from a TimeProvider<Clock> instance, and the timeout delay.

On timeout, Ready() is returned from the composed future's Pend().

Note however that this is indistinguishable from the Ready() returned from the ValueFuture<void> when it resolves without there being a timeout.

Strongly prefer instead to use TimeoutFutureWithDeadlineExceededAfter, as that gives you a Status.DeadlineExceeded() result instead.

TimeoutOrClosed() [1/4]

template<typename PrimaryFuture , int &... kExplicitGuard, typename = std::enable_if_t<!std::is_lvalue_reference_v<PrimaryFuture>>>

auto pw::async2::TimeoutOrClosed	(	PrimaryFuture &&	primary_future,
		typename chrono::SystemClock::duration	delay
	)

Helper function for using one of the other TimeoutOrClosed overloads which take a TimeProvider.

This overload uses the system time provider returned by the call to GetSystemTimeProvider(), and forwards it as the time provider along with the other arguments to the other overloads. See those other overloads to understand what type of future you will construct.

TimeoutOrClosed() [2/4]

template<typename T , typename Clock >

auto pw::async2::TimeoutOrClosed	(	ReceiveFuture< T > &&	future,
		TimeProvider< Clock > &	time_provider,
		typename Clock::duration	delay
	)

Constructs a FutureWithTimeout for a ReceiveFuture<T> as the primary future, a timeout future obtained from a TimeProvider<Clock> instance, and the timeout delay.

On timeout, the an empty std::optional<T> value is returned as the Ready(T) from the composed future's Pend().

Note that this return value means that the timeout return value is not distinguishable from the result when the channel is closed. If you prefer a distinct status value, use Timeout().

TimeoutOrClosed() [3/4]

template<typename T , typename Clock >

auto pw::async2::TimeoutOrClosed	(	ReserveSendFuture< T > &&	future,
		TimeProvider< Clock > &	time_provider,
		typename Clock::duration	delay
	)

Constructs a FutureWithTimeout for a SendFuture<T> as the primary future, a timeout future obtained from a TimeProvider<Clock> instance, and the timeout delay.

On timeout, the an empty optional<SendReservation<T>> value is returned as the Ready(T) from the composed future's Pend().

Note that this return value means that the timeout return value is not distinguishable from the result when the channel is closed. If you prefer a distinct status value, use Timeout().

TimeoutOrClosed() [4/4]

template<typename T , typename Clock >

auto pw::async2::TimeoutOrClosed	(	SendFuture< T > &&	future,
		TimeProvider< Clock > &	time_provider,
		typename Clock::duration	delay
	)

Constructs a FutureWithTimeout for a SendFuture<T> as the primary future, a timeout future obtained from a TimeProvider<Clock> instance, and the timeout delay.

On timeout, a boolean false value is returned as the Ready(T) from the composed future's Pend().

Note that this return value means that the timeout return value is not distinguishable from the result when the channel is closed. If you prefer a distinct status value, use Timeout().