idfxx::future< T > Class Template Reference

Async completion token. More...

Public Member Functions
	future ()=default
	Constructs an invalid (detached) future.
template<typename W > requires std::is_invocable_r_v<result<T>, W&, std::optional<std::chrono::milliseconds>>
	future (W waiter)
	Constructs a future from a waiter callable.
template<typename W , typename D > requires std::is_invocable_r_v<result<T>, W&, std::optional<std::chrono::milliseconds>> && std::is_nothrow_invocable_r_v<bool, const D&>
	future (W waiter, D done_check)
	Constructs a future with an explicit non-blocking done-check.
bool	valid () const noexcept
	Returns whether this future is associated with an async operation.
bool	done () const noexcept
	Non-blocking check for whether the operation has completed.
T	wait () const
	Blocks until the operation completes.
template<typename Rep , typename Period >
T	wait_for (const std::chrono::duration< Rep, Period > &timeout) const
	Blocks until the operation completes or the timeout expires.
result< T >	try_wait () const
	Blocks until the operation completes.
template<typename Rep , typename Period >
result< T >	try_wait_for (const std::chrono::duration< Rep, Period > &timeout) const
	Blocks until the operation completes or the timeout expires.

Detailed Description

template<typename T>
class idfxx::future< T >

Async completion token.

Provides a std::shared_future-like API for awaiting an asynchronous operation. Callers can block until completion (wait() / try_wait()), wait with a timeout (wait_for() / try_wait_for()), or poll for completion non-blockingly (done()).

A future is a lightweight, copyable handle: copies and moves are cheap, and it can be freely stored in containers. All copies share the same underlying operation, so a completion observed on one copy is visible on every other copy. Any resources held by the producer on behalf of the async operation are released automatically when the last copy is destroyed.

Template Parameters

T	The value type produced on successful completion. Use void for pure completion notifications.

auto f = make_async_op();      // returns idfxx::future<int>
int value = f.wait();          // blocks until ready
if (f.done()) { ... }          // non-blocking poll
auto v = f.try_wait_for(10ms); // returns result<int>

Definition at line 62 of file future.hpp.

Constructor & Destructor Documentation

future() [1/3]

template<typename T >

idfxx::future< T >::future ( )

default

Constructs an invalid (detached) future.

future() [2/3]

template<typename T >

template<typename W >
requires std::is_invocable_r_v<result<T>, W&, std::optional<std::chrono::milliseconds>>

idfxx::future< T >::future ( W  waiter )

inlineexplicit

Constructs a future from a waiter callable.

Intended for producers exposing an async operation via future. The waiter is called to service wait() / try_wait() / try_wait_for() and must honour the timeout argument:

• std::nullopt — wait indefinitely;
• an explicit duration — wait at most that long;
• std::chrono::milliseconds{0} — non-blocking check, returning immediately.

The waiter returns result<T> — either the completed value or an error (typically idfxx::errc::timeout when the deadline expires).

With this constructor, done() is serviced by calling the waiter with a zero timeout. Prefer the two-argument constructor when a cheap, non-consuming completion check is available.

Template Parameters

W	Waiter callable type.

Parameters

waiter

Waiter callable.

Note

Any resource captured by the waiter (for example an RAII handle to an in-flight operation) is released automatically when the last copy of the future is destroyed.

Definition at line 94 of file future.hpp.

future() [3/3]

template<typename T >

template<typename W , typename D >
requires std::is_invocable_r_v<result<T>, W&, std::optional<std::chrono::milliseconds>> && std::is_nothrow_invocable_r_v<bool, const D&>

idfxx::future< T >::future ( W  waiter, D  done_check  )

inline

Constructs a future with an explicit non-blocking done-check.

Intended for producers that have a cheap, non-consuming way to check completion (e.g. an atomic flag). When supplied, done_check is called to service done() instead of the waiter, avoiding a spurious wait round-trip.

Template Parameters

W	Waiter callable type.
D	Done-check callable type (must be noexcept).

Parameters

waiter	Waiter callable (see single-argument constructor).
done_check	Non-blocking, noexcept completion check returning true when the operation has completed.

Definition at line 114 of file future.hpp.

Member Function Documentation

done()

template<typename T >

bool idfxx::future< T >::done ( ) const

noexcept

Non-blocking check for whether the operation has completed.

Returns

true if the operation is complete; also true for an invalid future. false if the operation is still in progress.

Definition at line 208 of file future.hpp.

try_wait()

template<typename T >

result< T > idfxx::future< T >::try_wait

(

)

const

Blocks until the operation completes.

Safe to call on an invalid future: returns a value-initialized value.

Returns

The completed value, or an error.

Definition at line 220 of file future.hpp.

Referenced by idfxx::future< T >::wait().

try_wait_for()

template<typename T >

template<typename Rep , typename Period >

result< T > idfxx::future< T >::try_wait_for

(

const std::chrono::duration< Rep, Period > &

timeout

)

const

Blocks until the operation completes or the timeout expires.

Template Parameters

Rep	Duration arithmetic type.
Period	Duration period type.

Parameters

timeout

Maximum time to wait for completion.

Returns

The completed value, or an error (idfxx::errc::timeout if the deadline expired).

Definition at line 233 of file future.hpp.

References idfxx::timeout.

Referenced by idfxx::future< T >::wait_for().

valid()

template<typename T >

bool idfxx::future< T >::valid ( ) const

inlinenoexcept

Returns whether this future is associated with an async operation.

Returns

true if the future was constructed from a producer and has not been moved-from; false for a default-constructed or moved-from future.

Definition at line 124 of file future.hpp.

wait()

template<typename T >

T idfxx::future< T >::wait ( ) const

inline

Blocks until the operation completes.

Safe to call on an invalid future: returns a value-initialized value.

Returns

The completed value.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 145 of file future.hpp.

References idfxx::future< T >::try_wait(), and idfxx::unwrap().

wait_for()

template<typename T >

template<typename Rep , typename Period >

T idfxx::future< T >::wait_for ( const std::chrono::duration< Rep, Period > &  timeout ) const

inline

Blocks until the operation completes or the timeout expires.

Template Parameters

Rep	Duration arithmetic type.
Period	Duration period type.

Parameters

timeout

Maximum time to wait for completion.

Returns

The completed value.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure or timeout.

Definition at line 160 of file future.hpp.

References idfxx::timeout, idfxx::future< T >::try_wait_for(), and idfxx::unwrap().

---

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

• idfxx_core/include/idfxx/future.hpp