eve.rt.future

Futures and promises for asynchronous value propagation.

A Future represents a value that may not yet be available, while a Promise is the producer side that completes the future with a value or an error. Together they provide a mechanism for asynchronous communication between different parts of the runtime.

Copyright

License

Boost Software License, Version 1.0

enum FutureState

struct Future Promise

class FutureError SharedState

fn cancelled promise rejected resolved

Types 5

classFutureError : Exception

Error thrown when attempting to retrieve a value from a future that was completed with an error.

Constructors

this(string msg, string file = __FILE__, size_t line = __LINE__)Construct a FutureError with the given message.

enumFutureState : ubyte

The state of a future's completion.

PENDINGThe future has not yet been completed.

RESOLVEDThe future was completed successfully with a value.

REJECTEDThe future was completed with an error.

CANCELLEDThe future was cancelled.

private classSharedState(T)

Shared state between a Future and its corresponding Promise.

This structure holds the actual value or error and synchronization primitives needed for thread-safe access.

Fields

T valueThe resolved value, valid only when state is RESOLVED.

string errorMsgError message if the future was rejected.

FutureState stateCurrent state of the future.

Mutex mutexMutex for thread-safe state transitions.

void delegate(T) @safe[] onResolveCallbacks to invoke when the future completes.

void delegate(string) @safe[] onRejectCallbacks to invoke when the future is rejected.

void delegate() @safe[] onCancelCallbacks to invoke when the future is cancelled.

Constructors

this()Construct a new shared state with initialized mutex.

structFuture(T)

A future represents a value that will be available at some point.

Futures are the read-only consumer side of the future/promise pair. They allow checking whether a value is available and retrieving it once the corresponding promise has been completed.

Parameters

`T`	The type of value this future will hold.

Fields

private SharedState!T sharedState

Methods

bool isCompleted() const @trusted nothrow @nogcCheck whether the future has been completed (resolved or rejected).

bool isResolved() const @trusted nothrow @nogcCheck whether the future was resolved successfully.

bool isRejected() const @trusted nothrow @nogcCheck whether the future was rejected with an error.

bool isCancelled() const @trusted nothrow @nogcCheck whether the future was cancelled.

bool isPending() const @trusted nothrow @nogcCheck whether the future is still pending.

T get() @trustedRetrieve the value from a resolved future.

Future!T then(void delegate(T) @safe callback) ref @trusted returnRegister a callback to be invoked when the future is resolved.

Future!T onError(void delegate(string) @safe callback) ref @trusted returnRegister a callback to be invoked when the future is rejected.

Future!T onCancel(void delegate() @safe callback) ref @trusted returnRegister a callback to be invoked when the future is cancelled.

structPromise(T)

A promise is the producer side of a future/promise pair.

The promise holder can complete the associated future by either resolving it with a value or rejecting it with an error.

Parameters

`T`	The type of value this promise will produce.

Fields

private SharedState!T sharedState

Methods

Future!T future() @safe nothrow @nogcGet the future associated with this promise.

void resolve(T value) @trustedComplete the promise successfully with a value.

void reject(string errorMsg) @trustedComplete the promise with an error.

void cancel() @trustedComplete the promise as cancelled.

Functions 4

fnPromise!T promise(T)() @safeCreate a new promise/future pair.

fnFuture!T resolved(T)(T value) @safeCreate an already-resolved future with the given value.

fnFuture!T rejected(T)(string errorMsg) @safeCreate an already-rejected future with the given error.

fnFuture!T cancelled(T)() @safeCreate an already-cancelled future.