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

Contains the API around Future implementation. More...

Classes

class  AbstractFakeFuture
 Base class for all FakeFutures. More...
 
class  AbstractFuture
 Base class for all Futures. More...
 
class  AbstractFuturesGroup
 Abstract class to allow aggregation of several futures. More...
 
class  FakeFuture
 Actual FakeFuture, it has the exact same API as Future and can be used in lieu of Future. More...
 
class  Future
 Represent a value to be obtained, in some asynchronous way, in the future. More...
 
class  FutureOutputListener
 Listener is the interface allowing to listen to changes of a Future output buffer (while being fed by a producer). More...
 
class  FutureStatusListener
 Listener is the interface allowing to listen to changes of a Future status. More...
 

Enumerations

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

Detailed Description

Contains the API around Future implementation.

A Future allows you to pass and get values across different units of executions (threads, or more likely on AVR MCU, the main program and an ISR).

Concepts applied in this API:

  • A Future holds a buffer for a future "output" value (any type, even void, i.e. no value)
  • A Future may also hold a storage "input" value (constant, any type) with same lifetime as the Future
  • A Future is either:
    • Not ready: its value has not been obtained yet (initial status)
    • Ready: its value has been fully set and not yet read by anyone
    • Error: an error occurred in the provider, hence no value will ever be held by this Future, the actual error has not yet been read by anyone
  • Output value providers must hold a reference (or pointer) to the Future they need to fill
  • Storage input value consumers must hold a reference (or pointer) to the Future in order to get its storage value
  • It is possible to subclass a Future to add last minute transformation on Future.get() method

Here is a simple usage example of this API, using PCINT0 interrupt to take a "snapshot" of 6 input buttons connected to all PORTB pins, after one of them has changed level:

// PCINT0 ISR
class ButtonsSnapshot {
public:
ButtonsSnapshot() : port_{0x3F, 0x3F} {
signal_.set_enable_pins(0x3F);
signal_.enable();
}
bool get_snapshot(uint8_t& snapshot) {
// Wait for future result
bool result = future_.get(snapshot);
// Reset future
future_ = std::move(Future<uint8_t>{});
return result;
}
private:
void take_snapshot() {
future_.set_future_value_(port_.get_PIN());
}
Future<uint8_t> future_;
DECL_PCINT_ISR_FRIENDS
};
REGISTER_PCI_ISR_METHOD(PCINT, ButtonsSnapshot, &ButtonsSnapshot::take_snapshot, board::InterruptPin::D8_PB0_PCI0)
int main() {
// Enable interrupts at startup time
sei();
// Initialize PORT and PCI through ButtonsSnapshot
ButtonsSnapshot snapshot_taker;
while (true) {
// Wait for the future to be filled in by the PCINT0 ISR
uint8_t snapshot = 0;
if (snapshot_taker.get_snapshot(snapshot)) {
// Do something with the obtained snapshot
}
}
}

Enumeration Type Documentation

◆ FutureStatus

enum future::FutureStatus : uint8_t
strong

Status of a Future.

A Future follows a strict lifecycle by passing through the various statuses defined here.

See also
Future
Enumerator
NOT_READY 

The status of a Future immediately after it has been constructed.

The Future will keep this status until:

  • either its output value provider has fully filled its value (then its status will become READY)
  • or its output value provider has reported an error to it (then its status will become ERROR)
See also
Future.set_future_value_()
Future.set_future_finish()
Future.set_future_error()
READY 

The status of a Future once its output value has been fully set by a provider.

See also
Future.set_future_value()
Future.set_future_finish()
Future.get()
ERROR 

The status of a Future once a value provider has reported an error to it.

See also
Future.set_future_error()
Future.error()
INVALID 

The status of a Future that has been moved, if it was NOT_READY before moving.

Definition at line 118 of file future.h.

gpio::FastPort
API that manipulates a whole digital IO port.
Definition: gpio.h:202
std::move
constexpr types_traits::remove_reference< T >::type && move(T &&t)
Obtain an "rvalue" reference.
Definition: move.h:40
board::init
static void init()
Performs special initialization for ATmega644, actually nothing at all.
Definition: atmega_xx4.h:49
interrupt::PCISignal
Handler of a Pin Change Interrupt vector.
Definition: pci.h:176
interrupt::register_handler
void register_handler(Handler &handler)
Register a class instance containing methods that shall be called back by an ISR.
Definition: interrupts.h:157
REGISTER_PCI_ISR_METHOD
#define REGISTER_PCI_ISR_METHOD(PCI_NUM, HANDLER, CALLBACK, PIN,...)
Register the necessary ISR (Interrupt Service Routine) for a Pin Change Interrupt vector.
Definition: pci.h:44