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

BSD-3-Clause

enum CompletionPolicy FutureState

struct Future Promise

class AllCancel AllReject AllResolve AllState AnyCancel AnyReject AnyResolve AnyState DeferredCancel DeferredReject DeferredResolve FutureError RaceCancel RaceReject RaceResolve RaceState RetryState SharedState

fn all any cancelAll cancelled promise promiseWithLoop race rejected resolved retry timeout

Types 22

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.

enumCompletionPolicy

Policy controlling when completion callbacks execute.

When a Promise is created with an EventLoop, the policy determines how then()/onError()/onCancel() callbacks are delivered:

INLINE — callbacks execute immediately on the thread
calling resolve()/reject()/cancel(). This is the default and matches the historical behaviour.

DEFERRED — callbacks are queued via EventLoop.defer()
and execute on the next loop iteration. This prevents reentrancy and guarantees callbacks run on the loop thread.

DEFERRED requires an EventLoop. If no loop is available, callbacks execute inline regardless of the policy.

INLINEExecute callbacks immediately on the resolving thread.

DEFERREDQueue callbacks to the next EventLoop iteration.

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.

EventLoop * loopOptional EventLoop for deferred completion.

CompletionPolicy policyCompletion policy.

Constructors

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

this(EventLoop * loop, CompletionPolicy policy)Construct with EventLoop and policy.

private classDeferredResolve(T)

Fields

void delegate(T) @safe cb

T value

Methods

void run() @safe nothrow

Constructors

this(void delegate(T) @safe cb, T value)

private classDeferredReject(T)

Fields

void delegate(string) @safe cb

string errorMsg

Methods

void run() @safe nothrow

Constructors

this(void delegate(string) @safe cb, string errorMsg)

private classDeferredCancel

Fields

void delegate() @safe cb

Methods

void run() @safe nothrow

Constructors

this(void delegate() @safe cb)

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.

Future!U map(U)(U delegate(T) @safe fn) @trustedTransform the future's value with a mapping function, returning a new future that resolves with the mapped result.

Future!T fallback(T defaultValue) @trustedProvide a fallback value if this future is rejected.

Future!T withCancel(CancelToken token) @trustedAttach an external cancellation token to this future.

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.

private classAllState(T)

Create a future that resolves when all input futures resolve.

If any input is cancelled, the returned future is rejected with an error message and all remaining pending promises are cancelled. If any input rejects, the returned future rejects with that error message and all remaining pending promises are cancelled.

Parameters

promises Array of promises whose futures to join.

Returns

A future that resolves with an array of all values once every input

has resolved.

Fields

Promise!(T[]) joined

T[] results

size_t remaining

Promise!T[] promises

Methods

void onResolve(size_t i, T val) @safe

void onReject(string msg) @safe

void onCancel() @safe

Constructors

this(Promise!(T[]) joined, size_t count, Promise!T[] promises)

private classAllResolve(T)

Fields

AllState!T state

size_t idx

Methods

void opCall(T val) @safe

Constructors

this(AllState!T state, size_t idx)

private classAllReject(T)

Fields

AllState!T state

Methods

void opCall(string msg) @safe

Constructors

this(AllState!T state)

private classAllCancel(T)

Fields

AllState!T state

Methods

void opCall() @safe

Constructors

this(AllState!T state)

private classRaceState(T)

Create a future that resolves or rejects with the first input to complete.

Once a winner is determined, all remaining pending promises are cancelled. If the race future itself is cancelled externally, all inputs are cancelled.

Parameters

promises Array of promises whose futures to race.

Returns

A future that resolves with the value of the first input to resolve,

or rejects if the first input to complete rejects or is cancelled.

Fields

Promise!T winner

bool done

Promise!T[] promises

Methods

void onResolve(T val) @safe

void onReject(string msg) @safe

void onCancel() @safe

Constructors

this(Promise!T winner, Promise!T[] promises)

private classRaceResolve(T)

Fields

RaceState!T state

Methods

void opCall(T val) @safe

Constructors

this(RaceState!T state)

private classRaceReject(T)

Fields

RaceState!T state

Methods

void opCall(string msg) @safe

Constructors

this(RaceState!T state)

private classRaceCancel(T)

Fields

RaceState!T state

Methods

void opCall() @safe

Constructors

this(RaceState!T state)

private classAnyState(T)

Fields

Promise!T output

size_t remaining

string[] errors

Promise!T[] promises

Methods

void onResolve(T val) @safe

void onReject(size_t i, string msg) @safe

void onCancel(size_t i) @safe

Constructors

this(Promise!T output, size_t count, Promise!T[] promises)

private classAnyResolve(T)

Fields

AnyState!T state

Methods

void opCall(T val) @safe

Constructors

this(AnyState!T state)

private classAnyReject(T)

Fields

AnyState!T state

size_t idx

Methods

void opCall(string msg) @safe

Constructors

this(AnyState!T state, size_t idx)

private classAnyCancel(T)

Fields

AnyState!T state

size_t idx

Methods

void opCall() @safe

Constructors

this(AnyState!T state, size_t idx)

private classRetryState(T)

Fields

Promise!T output

T delegate() @safe factory

int maxAttempts

int attempts

long delayMs

EventLoop * loop

Methods

void attempt() @safe nothrow

Constructors

this(Promise!T output, T delegate() @safe factory, int maxAttempts, long delayMs, EventLoop * loop)

Functions 11

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

fnPromise!T promiseWithLoop(T)(EventLoop * loop, CompletionPolicy policy = CompletionPolicy.DEFERRED) @trustedCreate a promise/future pair with EventLoop integration.

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.

fnvoid cancelAll(T)(ref Promise!T[] promises) @safe nothrowCancel all promises in an array.

fnFuture!(T[]) all(T)(Promise!T[] promises) @trusted

fnFuture!T race(T)(Promise!T[] promises) @trusted

fnFuture!T any(T)(Promise!T[] promises) @trustedResolve with the first successfully resolved future, or reject if all fail.

fnFuture!T timeout(T)(Future!T input, ref EventLoop loop, long timeoutMs) @trustedApply a timeout to a future using an event loop.

fnFuture!T retry(T)(T delegate() @safe factory, int maxAttempts, long delayMs = 0, EventLoop * loop = null) @trustedRetry a synchronous operation up to maxAttempts times.