FastArduino  v1.8
C++ library to build fast but small Arduino/AVR projects
future::AbstractFuture Class Reference

Base class for all Futures. More...

#include <fastarduino/future.h>

Inheritance diagram for future::AbstractFuture:

Public Types

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

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...
 

Friends

template<typename F >
class AbstractFuturesGroup
 

Detailed Description

Base class for all Futures.

This defines most API and implementation of a Future.

See also
Future

Definition at line 222 of file future.h.

Member Typedef Documentation

◆ STATUS_LISTENER

The type to use for status listeners for this type of Future.

See also
FutureStatusListener

Definition at line 573 of file future.h.

◆ OUTPUT_LISTENER

The type to use for output listeners for this type of Future.

See also
FutureOutputListener

Definition at line 579 of file future.h.

Member Function Documentation

◆ status()

FutureStatus future::AbstractFuture::status ( ) const
inline

The current status of this Future.

See also
FutureStatus

Definition at line 230 of file future.h.

◆ await()

FutureStatus future::AbstractFuture::await ( ) const
inline

Wait until this Future becomes "ready", that is when it holds either an output value or an error.

Returns
the latest status of the Future
See also
Future.get()
error()

Definition at line 244 of file future.h.

◆ error()

int future::AbstractFuture::error ( ) const
inline

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

Return values
0if the Future is READY, i.e. holds a valid output value
Returns
the actual error reported by a provider on this Future
See also
await()
set_future_error_()
errors::EINVAL

Definition at line 262 of file future.h.

◆ get_storage_value_size_()

uint8_t future::AbstractFuture::get_storage_value_size_ ( ) const
inline

Check the number of bytes remaining to read from this Future.

This method is called by a Future input value consumer to know how many bytes remain to get read until the end of the input value.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Returns
the number of bytes to be read from the input value stored by this Future
See also
get_storage_value_()

Definition at line 294 of file future.h.

◆ get_storage_value_() [1/2]

bool future::AbstractFuture::get_storage_value_ ( uint8_t &  chunk)
inline

Get one byte from the input storage value of this Future.

This method is called by a Future input value consumer to consume the input value held by a Future. Every call to this method will advance the Future internal pointer to input data, so that next call will return the next byte of data. Calling this method never changes the status of the Future, hence it is not possible to read the input value more than once. This method is useful only for Future<?, T> where T type is not void.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Parameters
chunkthe byte reference that will receive the next byte of this Future input value
Return values
trueif the next byte of this Future could be read successfully
falseif all bytes of this Future input storage value have been read already
See also
get_storage_value_size_()
get_storage_value(uint8_t*, uint8_t)
Future::Future(const IN&)

Definition at line 323 of file future.h.

◆ get_storage_value_() [2/2]

bool future::AbstractFuture::get_storage_value_ ( uint8_t *  chunk,
uint8_t  size 
)
inline

Get size bytes from the input storage value of this Future.

This method is called by a Future input value consumer to consume the input value held by a Future. Every call to this method will advance the Future internal pointer to input data, so that next call will return the next chunk of data. Calling this method never changes the status of the Future, hence it is not possible to read the input value more than once. This method is useful only for Future<?, T> where T type is not void.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Parameters
chunka pointer to an array of at least size bytes, which will be filled with the next chunk of bytes of this Future input value
sizethe number of bytes to get from the input storage value
Return values
trueif the right amount bytes of this Future could be read successfully
falseif size is larger than the remaining number of bytes to be read from the input storage value
See also
get_storage_value_size_()
Future::Future(const IN&)
get_storage_value_(uint8_t&)

Definition at line 359 of file future.h.

◆ get_future_value_size_()

uint8_t future::AbstractFuture::get_future_value_size_ ( ) const
inline

Check the number of bytes remaining to write to the output value of this Future.

This method is called by a Future output value producer to know how many bytes remain to write until the end of the output value.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Returns
the number of bytes to be written to the output value stored in this Future
See also
set_future_finish_()
set_future_value_()

Definition at line 388 of file future.h.

◆ set_future_finish_()

bool future::AbstractFuture::set_future_finish_ ( )
inline

Mark this Future as FutureStatus::READY.

This method is called by a Future ouput value provider to indicate that a Future is ready for use. This method is useful only for Future<void> i.e. Futures that have no output, but exist as a way to indicate the end of an asynchronous process. For other Future<T>s, with a non void type T, you should use one of set_future_value_ methods instead.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Return values
falseif this Future cannot be updated properly (because it is not in FutureStatus::NOT_READY or if it is still expecting data)
trueif this Future has been properly updated
See also
status()
set_future_value_()
set_future_error_()

Definition at line 413 of file future.h.

◆ set_future_value_() [1/3]

bool future::AbstractFuture::set_future_value_ ( uint8_t  chunk)
inline

Add one byte to the output value content of this Future.

This method is called by a Future ouput value provider to fill up, byte after byte, the output value of a Future. Calling this method may change the status of the Future to FutureStatus::READY if this is the last output value byte to be filled for this Future. This method is useful only for Future<T> where T type is not void. You should not use it for a Future<void> instance.

It is also possible to fill the output value by larger chunks, with other overloaded versions of this method.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Parameters
chunkthe byte to append to this Future output value
Return values
trueif chunk could be added to the future
falseif this method failed; typically, when the current status of this Future is not FutureStatus::NOT_READY
See also
status()
set_future_value_(const uint8_t*, uint8_t)
set_future_value_(const T&)

Definition at line 450 of file future.h.

◆ set_future_value_() [2/3]

bool future::AbstractFuture::set_future_value_ ( const uint8_t *  chunk,
uint8_t  size 
)
inline

Add several bytes to the output value content of this Future.

This method is called by a Future ouput value provider to fill up, with a chunk of bytes, the output value of a Future. Calling this method may change the status of the Future to FutureStatus::READY if this is the last output value chunk to be filled for this Future. This method is useful only for Future<T> where T type is not void. You should not use it for a Future<void> instance.

It is also possible to fill the output value byte per byte, with other overloaded versions of this method.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Parameters
chunkpointer to the first byte to be added to this Future output value
sizethe number of bytes to be appended to this Future output value
Return values
trueif chunk could be completely added to the future
falseif this method failed; typically, when the current status of the target Future is not FutureStatus::NOT_READY, or when size additional bytes would make the output value bigger than expected
See also
status()
set_future_value_(uint8_t)
set_future_value_(const T&)

Definition at line 495 of file future.h.

◆ set_future_value_() [3/3]

template<typename T >
bool future::AbstractFuture::set_future_value_ ( const T &  value)
inline

Set the output value content of this Future.

This method is called by a Future ouput value provider to fully fill up, with the proper value, the output value of a Future. Calling this method will change the status of the Future to FutureStatus::READY This method is useful only for Future<T> where T type is not void.

It is also possible to fill the output value byte per byte, with other overloaded versions of this method.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Template Parameters
Tthe type of output value of this Future
Parameters
valuea constant reference to the value to set in this Future
Return values
trueif value could be properly set into the future
falseif this method failed; typically, when the current status of the target Future is not FutureStatus::NOT_READY
See also
status()
set_future_value_(uint8_t)
set_future_value_(const uint8_t*, uint8_t)

Definition at line 536 of file future.h.

◆ set_future_error_()

bool future::AbstractFuture::set_future_error_ ( int  error)
inline

Mark this Future as FutureStatus::ERROR.

This method is called by a Future ouput value provider to indicate that it cannot compute an output value for a given Future.

Warning
This method is not synchronized, it shall be called exclusively from an ISR, or possibly from inside a synchronized block.
Parameters
errorthe error code to set for the Future
Return values
trueif this Future has been properly updated
falseif this Future cannot be updated properly (because it is not in FutureStatus::NOT_READY)
See also
status()
set_future_value_()
set_future_finish_()

Definition at line 558 of file future.h.


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