Utility API to handle the concept of futures. More...

#include <string.h>
#include "flash.h"
#include "interrupts.h"
#include "iterator.h"
#include "errors.h"
#include "time.h"

Include dependency graph for future.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	future::AbstractFuture
	Base class for all `Future`s. More...

class	future::Future< OUT_, IN_ >
	Represent a value to be obtained, in some asynchronous way, in the future. More...

class	future::AbstractFakeFuture
	Base class for all `FakeFuture`s. More...

class	future::FakeFuture< OUT_, IN_ >
	Actual FakeFuture, it has the exact same API as Future and can be used in lieu of Future. More...

class	future::AbstractFuturesGroup< F >
	Abstract class to allow aggregation of several futures. More...

Namespaces
namespace	future
	Contains the API around Future implementation.

Macros
#define	REGISTER_FUTURE_STATUS_LISTENERS(ABSTRACT_TYPE, HANDLER1, ...)
	Register the necessary callbacks that will be notified when a `future::Future` (or a `future::FakeFuture`) has its status changed. More...

#define	REGISTER_FUTURE_STATUS_NO_LISTENERS()
	Register no callback at all to Future status changes notification. More...

#define	REGISTER_FUTURE_OUTPUT_LISTENERS(ABSTRACT_TYPE, HANDLER1, ...)
	Register the necessary callbacks that will be notified when a `future::Future` (or a `future::FakeFuture`) has its output content filled in, even partly. More...

#define	REGISTER_FUTURE_OUTPUT_NO_LISTENERS()
	Register no callback at all to Future output buffer changes notification. More...

#define	REGISTER_FUTURE_NO_LISTENERS()
	Register no callback at all to any Future notification. More...

#define	DECL_FUTURE_LISTENERS_FRIEND template<typename> friend struct future::dispatch_handler_impl;
	This macro shall be used in a class containing a private callback method `void on_status_change(const ABSTRACT_TYPE&, FutureStatus)`, registered by `REGISTER_FUTURE_STATUS_LISTENERS`, or `void on_output_change(const ABSTRACT_TYPE&)`, registered by `REGISTER_FUTURE_OUTPUT_LISTENERS`. More...

Enumerations
enum class	future::FutureStatus : uint8_t { future::NOT_READY = 0 , future::READY , future::ERROR , future::INVALID }
	Status of a Future. More...

enum class	future::FutureNotification : uint8_t { future::NONE = 0 , future::STATUS = 1 , future::OUTPUT = 2 , future::BOTH = 3 }
	Notification(s) dispatched by a Future. More...

Detailed Description

Utility API to handle the concept of futures.

For general discussion about this concept, please check https://en.wikipedia.org/wiki/Futures_and_promises

Definition in file future.h.

Macro Definition Documentation

◆ REGISTER_FUTURE_STATUS_LISTENERS

#define REGISTER_FUTURE_STATUS_LISTENERS	(	ABSTRACT_TYPE,
		HANDLER1,
		...
	)

Value:

    namespace future                                                                                \
    {                                                                                               \
        void future_on_status_change_dispatch(const AbstractFuture& future, FutureStatus status)    \
        {                                                                                           \
            dispatch_handler<ABSTRACT_TYPE, AbstractFuture>::future_on_status_change<               \
                HANDLER1, ##__VA_ARGS__>(future, status);                                           \
        }                                                                                           \
        void future_on_status_change_dispatch(const AbstractFakeFuture& future, FutureStatus status)\
        {                                                                                           \
            dispatch_handler<ABSTRACT_TYPE, AbstractFakeFuture>::future_on_status_change<           \
                HANDLER1, ##__VA_ARGS__>(future, status);                                           \
        }                                                                                           \
    }                                                                                               \

Register the necessary callbacks that will be notified when a future::Future (or a future::FakeFuture) has its status changed.

Note: only Futures constructed with FutureNotification::STATUS or FutureNotification::BOTH notifications parameter will produce such notifications.

Each handler registered here will be notified of status changes for ALL futures producing such notifications.

Warning: this macro must be called only once, with all interested handlers classes; calling it more than once will lead to errors at link time.

Note: you do not need to call this macro if you do not use futures in your program (do note that I2C support does use futures, even if you don't care about futures).; When an I2C device needs you to register some of its classes, it is indicated in its API documentation.

Parameters

ABSTRACT_TYPE	one of `AbstractFuture` or `AbstractFakeFuture`; any other type will fail compilation.
HANDLER1	a class which registered instance will be notified, through its `void on_status_change(const ABSTRACT_TYPE&, FutureStatus)` method when a notifying future has its status changed.
...	other classes similar to HANDLER1.

See also: REGISTER_FUTURE_STATUS_NO_LISTENERS(); interrupt::register_handler

Definition at line 62 of file future.h.

◆ REGISTER_FUTURE_STATUS_NO_LISTENERS

#define REGISTER_FUTURE_STATUS_NO_LISTENERS ( )

Value:

void future::future_on_status_change_dispatch(const AbstractFuture&, FutureStatus) {} \

void future::future_on_status_change_dispatch(const AbstractFakeFuture&, FutureStatus) {}

Register no callback at all to Future status changes notification.

You normally do not need this macro, except if you:

use Futures (directly or indirectly, i.e. through I2C support API)
do not use future::AbstractFuturesGroup (directlty or indirectlty, some I2C devices use it)
you do not need to be called back when one of your Futures change state

Note: When an I2C device needs you to register some of its classes, it is indicated in its API documentation.

See also: REGISTER_FUTURE_STATUS_LISTENERS(); REGISTER_FUTURE_NO_LISTENERS()

Definition at line 90 of file future.h.

◆ REGISTER_FUTURE_OUTPUT_LISTENERS

#define REGISTER_FUTURE_OUTPUT_LISTENERS	(	ABSTRACT_TYPE,
		HANDLER1,
		...
	)

Value:

    namespace future                                                                        \
    {                                                                                       \
        void future_on_output_change_dispatch(const AbstractFuture& future)                 \
        {                                                                                   \
            dispatch_handler<ABSTRACT_TYPE, AbstractFuture>::future_on_output_change<       \
                HANDLER1, ##__VA_ARGS__>(future);                                           \
        }                                                                                   \
        void future_on_output_change_dispatch(const AbstractFakeFuture& future)             \
        {                                                                                   \
            dispatch_handler<ABSTRACT_TYPE, AbstractFakeFuture>::future_on_output_change<   \
                HANDLER1, ##__VA_ARGS__>(future);                                           \
        }                                                                                   \
    }                                                                                       \

Register the necessary callbacks that will be notified when a future::Future (or a future::FakeFuture) has its output content filled in, even partly.

Note: only Futures constructed with FutureNotification::OUTPUT or FutureNotification::BOTH notifications parameter will produce such notifications.

Each handler registered here will be notified of output changes for ALL futures producing such notifications.

Warning: this macro must be called only once, with all interested handlers classes; calling it more than once will lead to errors at link time.

Note: you do not need to call this macro if you do not use futures in your program (do note that I2C support does use futures, even if you don't care about futures).; When an I2C device needs you to register some of its classes, it is indicated in its API documentation.

Parameters

ABSTRACT_TYPE	one of `AbstractFuture` or `AbstractFakeFuture`; any other type will fail compilation.
HANDLER1	a class which registered instance will be notified, through its `void on_output_change(const ABSTRACT_TYPE&)` method when a notifying future has its output content filled in.
...	other classes similar to HANDLER1.

See also: REGISTER_FUTURE_OUTPUT_NO_LISTENERS(); interrupt::register_handler

Definition at line 123 of file future.h.

◆ REGISTER_FUTURE_OUTPUT_NO_LISTENERS

#define REGISTER_FUTURE_OUTPUT_NO_LISTENERS ( )

Value:

void future::future_on_output_change_dispatch(const AbstractFuture&) {} \

void future::future_on_output_change_dispatch(const AbstractFakeFuture&) {}

Register no callback at all to Future output buffer changes notification.

You normally do not need this macro, except if you:

use Futures (directly or indirectly, i.e. through I2C support API)
you do not need to be called back when one of your Futures change outut buffer

Note: When an I2C device needs you to register some of its classes, it is indicated in its API documentation.

See also: REGISTER_FUTURE_OUTPUT_LISTENERS(); REGISTER_FUTURE_NO_LISTENERS()

Definition at line 150 of file future.h.

◆ REGISTER_FUTURE_NO_LISTENERS

#define REGISTER_FUTURE_NO_LISTENERS ( )

Value:

REGISTER_FUTURE_STATUS_NO_LISTENERS() \

REGISTER_FUTURE_OUTPUT_NO_LISTENERS()

REGISTER_FUTURE_STATUS_NO_LISTENERS

#define REGISTER_FUTURE_STATUS_NO_LISTENERS()

Register no callback at all to Future status changes notification.

Definition: future.h:90

Register no callback at all to any Future notification.

You normally do not need this macro, except if you:

use Futures (directly or indirectly, i.e. through I2C support API)
you do not need to be called back when one of your Futures change outut buffer

Note: When an I2C device needs you to register some of its classes, it is indicated in its API documentation.

See also: REGISTER_FUTURE_STATUS_NO_LISTENERS(); REGISTER_FUTURE_OUTPUT_NO_LISTENERS()

Definition at line 166 of file future.h.

◆ DECL_FUTURE_LISTENERS_FRIEND

#define DECL_FUTURE_LISTENERS_FRIEND template<typename> friend struct future::dispatch_handler_impl;

This macro shall be used in a class containing a private callback method void on_status_change(const ABSTRACT_TYPE&, FutureStatus), registered by REGISTER_FUTURE_STATUS_LISTENERS, or void on_output_change(const ABSTRACT_TYPE&), registered by REGISTER_FUTURE_OUTPUT_LISTENERS.

It declares the class where it is used as a friend of all necessary functions so that the private callback method can be called properly.

Definition at line 178 of file future.h.

Classes

Namespaces

Macros

Enumerations

Detailed Description

Macro Definition Documentation

◆ REGISTER_FUTURE_STATUS_LISTENERS

◆ REGISTER_FUTURE_STATUS_NO_LISTENERS

◆ REGISTER_FUTURE_OUTPUT_LISTENERS

◆ REGISTER_FUTURE_OUTPUT_NO_LISTENERS

◆ REGISTER_FUTURE_NO_LISTENERS

◆ DECL_FUTURE_LISTENERS_FRIEND