fiber::Future< T > Class Template Reference

Future and Promise pairs are used to synchronise values between asynchronous tasks. More...

#include <Future.hpp>

Public Member Functions
	Future ()=default
	Future (const Future &)=delete
Future &	operator= (const Future &)=delete
Future &	operator= (Future &&oldFuture)
	Future (Future &&oldFuture)
	Thread and interrupt save move that re-registers stack pointer in between the future and the promise.
	~Future ()
bool	is_connected () const
bool	is_detatched () const
bool	is_connected_to (const Promise< T > &promise) const
	Checks if the promise is connected to the future.
void	wait ()
	Blocks the current thread until the value is ready or an error occured.
T &	get ()
	returns the value of the future and waits if necessary
T *	get_if ()
	returns the value of the future and waits if necessary. If the value does not exist, a nullptr is being returned
State	get_state () const
State	state () const
constexpr bool	is_ready () const
	returns true if the value is ready to read
constexpr	operator bool () const
	converts to a boolean. same as calling is_ready().
constexpr bool	is_waiting () const
	returns true if the result is not finished yet and one has to wait
constexpr bool	is_broken_promise () const
	return true if the promise was not kept
constexpr bool	await_ready () const noexcept
	co_await interoperability, returns true, if the future is no longer waiting.
std::optional< T >	await_resume () noexcept
	co_await interoperability and optionally returns a value if one has been set.

Friends
class	Promise< T >
FuturePromisePair< T >	make_future_promise ()
	creates a linked future promise pair

Detailed Description

template<class T>
class fiber::Future< T >

Future and Promise pairs are used to synchronise values between asynchronous tasks.

If you are on a multi core bare-metal embedded system you can set the FIBER_MULTI_CORE definiteion flag that will enable safeguards and lock mechanisms - smaller binary and faster execution. In single core mode (FIBER_MULTI_CORE=OFF), it will then remove all the locks and logic that is needed for multi-core thread safety.

Example: one wants to copy data asynchronously (for example with a DMA controller) while doing some computations in the mean time.

{
 
     // You want to calculate for example the CRC code of some data and use a hardware module that can do that independently
     // The function issues a request to a hardware-unit/co-processor and returns immediately
     // create a future that expects a result in the future
     Future<int> future_crc = async_crc(data, dataLength);;
 
     future_crc.is_ready(); // returns `false`
 
     // In the mean time, while the CRC is being calculated, one can do some calculations
     // ...
     // ... some math ...
     // ...
     
     // later you you want to get the value from the future - aka. the CRC calculation you call:
     int crc = future_crc.get(); // the method waits and blocks this thread until the future value is ready
 
} // alternatively, if you do not wait or get the value, the future and promise safely detatch in the destructor

To create a future promise pair use:

auto [future, promise] = fiber::make_future_promise<int>();

Constructor & Destructor Documentation

Future() [1/3]

template<class T>

fiber::Future< T >::Future ( )

default

Future() [2/3]

template<class T>

fiber::Future< T >::Future ( const Future< T > & )

delete

Future() [3/3]

template<class T>

fiber::Future< T >::Future ( Future< T > && oldFuture )

inline

Thread and interrupt save move that re-registers stack pointer in between the future and the promise.

~Future()

template<class T>

fiber::Future< T >::~Future ( )

inline

Member Function Documentation

await_ready()

template<class T>

bool fiber::Future< T >::await_ready ( ) const

inlineconstexprnoexcept

co_await interoperability, returns true, if the future is no longer waiting.

Returns true if the future is not waiting anymore. Note that this does not mean that it has a readable value. It could also be broken, because the promise died before it could write a value

Returns

true if the Future is no longer waiting on the Promise

await_resume()

template<class T>

std::optional< T > fiber::Future< T >::await_resume ( )

inlinenoexcept

co_await interoperability and optionally returns a value if one has been set.

Returns

returns the value if the value has been set and is_ready() would also return true, returns a std::nullopt otherwise.

get()

template<class T>

T & fiber::Future< T >::get ( )

inlinenodiscard

returns the value of the future and waits if necessary

Exceptions

Exception

of type fiber::Exception if an error occured.

get_if()

template<class T>

T * fiber::Future< T >::get_if ( )

inlinenodiscard

returns the value of the future and waits if necessary. If the value does not exist, a nullptr is being returned

get_state()

template<class T>

State fiber::Future< T >::get_state ( ) const

inlinenodiscard

is_broken_promise()

template<class T>

bool fiber::Future< T >::is_broken_promise ( ) const

inlinenodiscardconstexpr

return true if the promise was not kept

This happens when no value was assigned to the promise before deconstruction. If this happens an Exception (Derived from std::exception) will be thrown.

is_connected()

template<class T>

bool fiber::Future< T >::is_connected ( ) const

inline

is_connected_to()

template<class T>

bool fiber::Future< T >::is_connected_to ( const Promise< T > & promise ) const

inline

Checks if the promise is connected to the future.

Returns

true if the passed promise is the one connected to this future

is_detatched()

template<class T>

bool fiber::Future< T >::is_detatched ( ) const

inline

is_ready()

template<class T>

bool fiber::Future< T >::is_ready ( ) const

inlinenodiscardconstexpr

returns true if the value is ready to read

is_waiting()

template<class T>

bool fiber::Future< T >::is_waiting ( ) const

inlinenodiscardconstexpr

returns true if the result is not finished yet and one has to wait

operator bool()

template<class T>

fiber::Future< T >::operator bool ( ) const

inlinenodiscardconstexpr

converts to a boolean. same as calling is_ready().

operator=() [1/2]

template<class T>

Future & fiber::Future< T >::operator= ( const Future< T > & )

delete

operator=() [2/2]

template<class T>

Future & fiber::Future< T >::operator= ( Future< T > && oldFuture )

inline

state()

template<class T>

State fiber::Future< T >::state ( ) const

inline

wait()

template<class T>

void fiber::Future< T >::wait ( )

inline

Blocks the current thread until the value is ready or an error occured.

Friends And Related Symbol Documentation

make_future_promise

template<class T>

FuturePromisePair< T > make_future_promise ( )

friend

creates a linked future promise pair

Example:

auto [future, promise] = make_future_promise<int>();

Template Parameters

T	The type that is being promised by the promise and awaited by the future

Returns

A linked FuturePromisePair Future promise pair

Promise< T >

template<class T>

friend class Promise< T >

friend

---

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

• fiber/Future/Future.hpp