A future is a concurrency primitive that provides a mechanism to access results of asynchronous operations. More...

#include <xrt/xrt_future.h>

Inheritance diagram for xrt_future:

Collaboration diagram for xrt_future:

[legend]

Static Public Member Functions
static xrt_result_t	xrt_future_get_result (const struct xrt_future xft, struct xrt_future_result out_result)
	Helper function for xrt_future::get_result. More...

static xrt_result_t	xrt_future_get_state (const struct xrt_future xft, enum xrt_future_state out_state)
	Helper function for xrt_future::get_state. More...

static xrt_result_t	xrt_future_cancel (struct xrt_future *xft)
	Helper function for xrt_future::cancel. More...

static xrt_result_t	xrt_future_wait (struct xrt_future *xft, int64_t timeout)
	Helper function for xrt_future::wait. More...

static xrt_result_t	xrt_future_is_cancel_requested (const struct xrt_future xft, bool out_request_cancel)
	Helper function for xrt_future::is_cancel_requested. More...

static xrt_result_t	xrt_future_complete (struct xrt_future xft, const struct xrt_future_result ft_result)
	Helper function for xrt_future::complete. More...

Data Fields
struct xrt_reference	reference
	Reference helper. More...

void(*	destroy )(struct xrt_future *xft)
	Destroys the future. More...

xrt_result_t(*	get_state )(const struct xrt_future xft, enum xrt_future_state out_state)
	Gets the current state of the future. More...

xrt_result_t(*	get_result )(const struct xrt_future xft, struct xrt_future_result out_result)
	Gets the future results (after async operation has finished) More...

xrt_result_t(*	cancel )(struct xrt_future *xft)
	Signals an asynchronous operation associated with the future to cancel. More...

xrt_result_t(*	wait )(struct xrt_future *xft, int64_t timeout_ns)
	Waits on a pending/cancelled future. More...

xrt_result_t(*	is_cancel_requested )(const struct xrt_future xft, bool out_request_cancel)
	Waits on a cancelled future. More...

xrt_result_t(*	complete )(struct xrt_future xft, const struct xrt_future_result ft_result)
	Signals that the asynchronous operation has completed and sets the future’s result. More...

Related Functions
(Note that these are not member functions.)
static void	xrt_future_reference (struct xrt_future *dst, struct xrt_future src)
	Update the reference counts on xrt_future(s). More...

Detailed Description

A future is a concurrency primitive that provides a mechanism to access results of asynchronous operations.

The xrt_future interface shares similarities with OpenXR futures but is not identical. In comparison to C++ std::future, xrt_future combines concepts from both std::shared_future and std::promise with built-in cancellation support in a single interface. The interface provides separate method sets for producers (result generators) and consumers (result pollers/waiters).

Thread Safety and Reference Counting: Each thread that references an xrt_future must properly manage the reference count using xrt_future_reference when entering and exiting the thread's scope.

See also: "Server-side / driver — implementing async callbacks" in @ref /builds/monado/monado/doc/async-functions-and-futures.md "async-functions-and-futures" for producer example code

Member Function Documentation

◆ xrt_future_cancel()

static xrt_result_t xrt_future_cancel ( struct xrt_future * xft )

inlinestatic

Helper function for xrt_future::cancel.

Signals an asynchronous operation associated with the future to cancel.

Parameters

[in] xft The future.

Note: Consumer Interface; Blocking behavior - Non-blocking, may briefly block acquiring an internal mutex to check/consume state

References cancel.

◆ xrt_future_complete()

static xrt_result_t xrt_future_complete	(	struct xrt_future *	xft,
		const struct xrt_future_result *	ft_result
	)

inlinestatic

Helper function for xrt_future::complete.

Signals that the asynchronous operation has completed and sets the future’s result.

Parameters

[in]	xft	The future.
[in]	ft_result	the result of an async operation associated with xft.

Note: Producer interface; Blocking behavior - Non-blocking, may briefly block acquiring an internal mutex to check/consume state; Differs from OpenXR future/async complete functions as those are used to only get the results of a future once the async-operation has finished where as this callback is used by async operation to mark/signal completion and return a result; Similar to std::promise::set_value

See also: xrt_future::get_result, xrt_future_result, xrt_future_value

References complete.

◆ xrt_future_get_result()

static xrt_result_t xrt_future_get_result	(	const struct xrt_future *	xft,
		struct xrt_future_result *	out_result
	)

inlinestatic

Helper function for xrt_future::get_result.

Gets the future results (after async operation has finished)

Parameters

[in]	xft	The future.
[out]	out_result	The future result of xft

Note: Consumer Interface; Blocking behavior - Non-blocking w.r.t. result: returns immediately, may briefly block acquiring an internal mutex to check/consume state; differs from std::future::get in that std::future will block & wait the calling thread until the result is ready where as xrt_future::get_result is non-blocking (w.r.t. result) to achieve the equivalent without using polling interface would be:

// std::future::get == xrt_future_wait(xft, INT64_MAX); xrt_get_result(xft, &my_result);

Note: Similar to or used by OpenXR future/async complete functions

See also: xrt_future::complete, xrt_future_result, xrt_future_value

References get_result.

◆ xrt_future_get_state()

static xrt_result_t xrt_future_get_state	(	const struct xrt_future *	xft,
		enum xrt_future_state *	out_state
	)

inlinestatic

Helper function for xrt_future::get_state.

Gets the current state of the future.

Parameters

[in]	xft	The future.
[out]	out_state	The current state of xft

Note: Consumer Interface; Blocking behavior - non-blocking

See also: xrt_future_state

References get_state.

◆ xrt_future_is_cancel_requested()

static xrt_result_t xrt_future_is_cancel_requested	(	const struct xrt_future *	xft,
		bool *	out_request_cancel
	)

inlinestatic

Helper function for xrt_future::is_cancel_requested.

Waits on a cancelled future.

Parameters

[in]	xft	The future.
[out]	out_request_cancel	Has the consumer requested to cancel the async operation?

Note: Producer interface; Blocking behavior - non-blocking

See also: xrt_future::cancel

References is_cancel_requested.

◆ xrt_future_wait()

static xrt_result_t xrt_future_wait	(	struct xrt_future *	xft,
		int64_t	timeout
	)

inlinestatic

Helper function for xrt_future::wait.

Waits on a pending/cancelled future.

Parameters

[in]	xft	The future.
[in]	timeout_ns	Timeout in nanoseconds or INT64_MAX for infinite duration

Note: Consumer Interface; Blocking behavior - Blocking

See also: xrt_future::cancel, xrt_future::complete

References wait.

Field Documentation

◆ cancel

xrt_result_t(* xrt_future::cancel) (struct xrt_future *xft)

Signals an asynchronous operation associated with the future to cancel.

Parameters

[in] xft The future.

Note: Consumer Interface; Blocking behavior - Non-blocking, may briefly block acquiring an internal mutex to check/consume state

Referenced by xrt_future_cancel().

◆ complete

xrt_result_t(* xrt_future::complete) (struct xrt_future *xft, const struct xrt_future_result *ft_result)

Signals that the asynchronous operation has completed and sets the future’s result.

Parameters

[in]	xft	The future.
[in]	ft_result	the result of an async operation associated with xft.

Note: Producer interface; Blocking behavior - Non-blocking, may briefly block acquiring an internal mutex to check/consume state; Differs from OpenXR future/async complete functions as those are used to only get the results of a future once the async-operation has finished where as this callback is used by async operation to mark/signal completion and return a result; Similar to std::promise::set_value

See also: xrt_future::get_result, xrt_future_result, xrt_future_value

Referenced by xrt_future_complete().

◆ destroy

void(* xrt_future::destroy) (struct xrt_future *xft)

Destroys the future.

Referenced by xrt_future_reference().

◆ get_result

xrt_result_t(* xrt_future::get_result) (const struct xrt_future *xft, struct xrt_future_result *out_result)

Gets the future results (after async operation has finished)

Parameters

[in]	xft	The future.
[out]	out_result	The future result of xft

Note: Consumer Interface; Blocking behavior - Non-blocking w.r.t. result: returns immediately, may briefly block acquiring an internal mutex to check/consume state; differs from std::future::get in that std::future will block & wait the calling thread until the result is ready where as xrt_future::get_result is non-blocking (w.r.t. result) to achieve the equivalent without using polling interface would be:

// std::future::get == xrt_future_wait(xft, INT64_MAX); xrt_get_result(xft, &my_result);