Represent a value to be obtained, in some asynchronous way, in the future. More...

#include <fastarduino/future.h>

Inheritance diagram for future::Future< OUT_, IN_ >:

Collaboration diagram for future::Future< OUT_, IN_ >:

Public Types
using	OUT = OUT_
	Type of the output value of this Future. More...

using	IN = IN_
	Type of the input value of this Future. More...

Public Member Functions
	Future (const IN &input=IN{}, FutureNotification notifications=FutureNotification::NONE)
	Construct a new Future. More...

void	reset_ (const IN &input=IN{})
	This method completely resets this future (for reuse from scratch), as if it was just constructed. More...

bool	reset_input_ (const IN &input)
	Reset the input storage value held by this Future with a new value. More...

bool	get (OUT &result)
	Wait until an output value has been completely filled in this Future and return that value to the caller. More...

Public Member Functions inherited from future::AbstractFuture
FutureStatus	status () const
	The current status of this Future. More...

FutureStatus	await () const
	Wait until this Future becomes "ready", that is when it holds either an output value or an error. More...

int	error () const
	Wait until this Future becomes "ready", that is when it holds either an output value or an error, then return the error reported. More...

uint8_t	get_storage_value_size_ () const
	Check the number of bytes remaining to read from this Future. More...

bool	get_storage_value_ (uint8_t &chunk)
	Get one byte from the input storage value of this Future. More...

bool	get_storage_value_ (uint8_t *chunk, uint8_t size)
	Get `size` bytes from the input storage value of this Future. More...

uint8_t	get_future_value_size_ () const
	Check the number of bytes remaining to write to the output value of this Future. More...

bool	set_future_finish_ ()
	Mark this Future as `FutureStatus::READY`. More...

bool	set_future_value_ (uint8_t chunk)
	Add one byte to the output value content of this Future. More...

bool	set_future_value_ (const uint8_t *chunk, uint8_t size)
	Add several bytes to the output value content of this Future. More...

template<typename T >
bool	set_future_value_ (const T &value)
	Set the output value content of this Future. More...

bool	set_future_error_ (int error)
	Mark this Future as `FutureStatus::ERROR`. More...

Static Public Attributes
static constexpr uint8_t	OUT_SIZE = sizeof(OUT)
	Size of the output value of this Future. More...

static constexpr uint8_t	IN_SIZE = sizeof(IN)
	Size of the input value of this Future. More...

Protected Member Functions
const IN &	get_input () const
	Return the input storage value as it was initially set (or reset through `reset_input_()`), whatever the current state of this Future. More...

IN &	get_input ()
	Return the input storage value as it was initially set (or reset through `reset_input_()`), whatever the current state of this Future. More...

Detailed Description

template<typename OUT_ = void, typename IN_ = void>
class future::Future< OUT_, IN_ >

Represent a value to be obtained, in some asynchronous way, in the future.

A Future can be thought of as a container (or buffer) that is here to receive some value that will be read later on. The value can be fed by some external function, either as a whole, or possibly byte per byte or even as chunks of bytes. This value is called an output value as it represents the output of some asynchronous function. A Future is also a holder for a constant value that is persistent as long as the Future persists; this value is called "input storage value" as it can serve as input to an asynchronous function. A Future can also hold an error code instead of a valid output value; that code is provided, when needed, by the asynchronous function computing the output value, if it encounters an unrecoverable error.

This is a template class where one can define the types of the input storage value and of the output value. Template specializations exist for OUT or IN void.

The lifecycle of a Future is described in further details in FutureStatus.

Template Parameters

OUT	the type of the output value; `void` by default. This type is limited to 255 bytes in length.
IN	the type of the input storage value; `void` by default. This type is limited to 255 bytes in length.

See also: AbstractFuture; FutureStatus

Definition at line 866 of file future.h.

Member Typedef Documentation

◆ OUT

template<typename OUT_ = void, typename IN_ = void>

using future::Future< OUT_, IN_ >::OUT = OUT_

Type of the output value of this Future.

Definition at line 873 of file future.h.

◆ IN

template<typename OUT_ = void, typename IN_ = void>

using future::Future< OUT_, IN_ >::IN = IN_

Type of the input value of this Future.

Definition at line 875 of file future.h.

Constructor & Destructor Documentation

◆ Future()

template<typename OUT_ = void, typename IN_ = void>

future::Future< OUT_, IN_ >::Future	(	const IN &	input = `IN{}`,
		FutureNotification	notifications = `FutureNotification::NONE`
	)

inlineexplicit

Construct a new Future.

The created Future is in FutureStatus::NOT_READY status. The Future holds buffers to store both the input storage value and the output value.

Parameters

input	a value to be copied to this Future input storage value; this argument does not exist when `IN` is `void`.
notifications	determines if and which notifications should be dispatched by this Future; default is none.

See also: AbstractFuture; FutureNotification; status(); FutureStatus

Definition at line 898 of file future.h.

Member Function Documentation

◆ reset_()

template<typename OUT_ = void, typename IN_ = void>

void future::Future< OUT_, IN_ >::reset_ ( const IN & input = IN{} )

inline

This method completely resets this future (for reuse from scratch), as if it was just constructed.

This allows reuse of a single future several times.

Parameters

input a value to be copied to this Future input storage value; this argument does not exist when IN is void.

Definition at line 914 of file future.h.

◆ reset_input_()

template<typename OUT_ = void, typename IN_ = void>

bool future::Future< OUT_, IN_ >::reset_input_ ( const IN & input )

inline

Reset the input storage value held by this Future with a new value.

This is possible only if no consumer has started reading the current input storage value yet.

Warning: This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.

Parameters

input a value to be copied to this Future input storage value; this argument does not exist when IN is void.

Return values

true	if the input strage value has been successfully replaced
false	if the input strage value could not be replaced because a consumer already started reading the previous input storage value

Definition at line 934 of file future.h.

◆ get()

template<typename OUT_ = void, typename IN_ = void>

bool future::Future< OUT_, IN_ >::get ( OUT & result )

inline

Wait until an output value has been completely filled in this Future and return that value to the caller.

This method should never be called from an ISR as it is blocking for an undetermined time!

Parameters

result a reference to a variable that will be assigned the output value, once available; if an error occurred, result is unchanged. This argument does not exist when OUT is void

Return values

true	if an output value has been set to this Future and it was assigned to `result`
false	if an error was reported to this Future; the error can be obtained through `error()`.

See also: await(); error(); FutureStatus::READY; FutureStatus::ERROR

Definition at line 961 of file future.h.

◆ get_input() [1/2]

template<typename OUT_ = void, typename IN_ = void>

const IN & future::Future< OUT_, IN_ >::get_input ( ) const

inlineprotected

Return the input storage value as it was initially set (or reset through reset_input_()), whatever the current state of this Future.

See also: reset_input_()

Definition at line 975 of file future.h.

◆ get_input() [2/2]

template<typename OUT_ = void, typename IN_ = void>

IN & future::Future< OUT_, IN_ >::get_input ( )

inlineprotected

Return the input storage value as it was initially set (or reset through reset_input_()), whatever the current state of this Future.

See also: reset_input_()

Definition at line 985 of file future.h.

Member Data Documentation

◆ OUT_SIZE

template<typename OUT_ = void, typename IN_ = void>

constexpr uint8_t future::Future< OUT_, IN_ >::OUT_SIZE = sizeof(OUT)

staticconstexpr

Size of the output value of this Future.

Definition at line 878 of file future.h.

◆ IN_SIZE

template<typename OUT_ = void, typename IN_ = void>

constexpr uint8_t future::Future< OUT_, IN_ >::IN_SIZE = sizeof(IN)

staticconstexpr

Size of the input value of this Future.

Definition at line 880 of file future.h.

◆ output_

template<typename OUT_ = void, typename IN_ = void>

OUT future::Future< OUT_, IN_ >::output_

Definition at line 993 of file future.h.

◆ output_buffer_

template<typename OUT_ = void, typename IN_ = void>

uint8_t future::Future< OUT_, IN_ >::output_buffer_[sizeof(OUT)]

Definition at line 994 of file future.h.

◆ input_

template<typename OUT_ = void, typename IN_ = void>

IN future::Future< OUT_, IN_ >::input_

Definition at line 998 of file future.h.

◆ input_buffer_

template<typename OUT_ = void, typename IN_ = void>

uint8_t future::Future< OUT_, IN_ >::input_buffer_[sizeof(IN)]

Definition at line 999 of file future.h.

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

fastarduino/future.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ OUT

◆ IN

Constructor & Destructor Documentation

◆ Future()

Member Function Documentation

◆ reset_()

◆ reset_input_()

◆ get()

◆ get_input() [1/2]

◆ get_input() [2/2]

Member Data Documentation

◆ OUT_SIZE

◆ IN_SIZE

◆ output_

◆ output_buffer_

◆ input_

◆ input_buffer_