FastArduino  v1.8
C++ library to build fast but small Arduino/AVR projects
future::Future< OUT_, IN_ > Class Template Reference

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.
 
using IN = IN_
 Type of the input value of this Future.
 
- Public Types inherited from future::AbstractFuture
using STATUS_LISTENER = FutureStatusListener< AbstractFuture >
 The type to use for status listeners for this type of Future. More...
 
using OUTPUT_LISTENER = FutureOutputListener< AbstractFuture >
 The type to use for output listeners for this type of Future. More...
 

Public Member Functions

 Future (const IN &input=IN{}, STATUS_LISTENER *status_listener=nullptr, OUTPUT_LISTENER *output_listener=nullptr)
 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.
 
static constexpr uint8_t IN_SIZE = sizeof(IN)
 Size of the input value of this Future.
 

Protected Member Functions

const INget_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...
 
INget_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
OUTthe type of the output value; void by default. This type is limited to 255 bytes in length.
INthe 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 701 of file future.h.

Constructor & Destructor Documentation

◆ Future()

template<typename OUT_ = void, typename IN_ = void>
future::Future< OUT_, IN_ >::Future ( const IN input = IN{},
STATUS_LISTENER status_listener = nullptr,
OUTPUT_LISTENER output_listener = nullptr 
)
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
inputa value to be copied to this Future input storage value; this argument does not exist when IN is void.
status_listeneran optional listener to status changes on this future
output_listeneran optional listener to output buffer changes on this future
See also
AbstractFuture
status()
FutureStatus

Definition at line 734 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
inputa value to be copied to this Future input storage value; this argument does not exist when IN is void.

Definition at line 764 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
inputa value to be copied to this Future input storage value; this argument does not exist when IN is void.
Return values
trueif the input strage value has been successfully replaced
falseif the input strage value could not be replaced because a consumer already started reading the previous input storage value

Definition at line 784 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
resulta 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
trueif an output value has been set to this Future and it was assigned to result
falseif 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 811 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 825 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 835 of file future.h.


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