GdbPromise¶

Promise for GDScript.

Description¶

A promise settles once, with a resolved value or a rejection reason. Create one with an executor callable that receives resolve and reject callables:

var loaded := GdbPromise.new(func(resolve: Callable, reject: Callable):
    var result := await load_level()
    if result.ok:
        resolve.call(result.level)
    else:
        reject.call(result.error)
)
var level = await loaded.await_resolved()

Chain work with then() and catch(), combine promises with all() and race(), and wrap callables and signals with to_promise(). Settled promises are safe to await again.

Tutorials¶

Promises

Properties¶

bool	is_settled
bool	is_resolved
bool	is_rejected
Status	status
Variant	result
Variant	value
int	id	`_id_counter`

Methods¶

void	_init(callback: Callable = <anonymous lambda>)
GdbPromise	then(on_fulfilled: Callable)
GdbPromise	catch(callback: Callable)
GdbPromise	finally(callback: Callable)
Variant	await_resolved()
void	await_settled()
Variant	await_rejected()
Variant	await_then()
Variant	await_catch()
void	await_finally()
void	resolve(value_: Variant = null)
void	reject(reason: Variant = null)
GdbPromise	new_resolved(value_: Variant = null) static
GdbPromise	new_rejected(reason: Variant = null) static
GdbPromise	all(promises: Array) static
GdbPromise	race(promises: Array) static
GdbPromise	sleep(duration: float) static
GdbPromise	timeout(duration: float, reason: Variant = &”timeout”) static
GdbPromise	to_promise(thing: Variant) static
GdbPromise	from_signals(success_signal: Signal, failure_signal: Signal = Signal()) static

Signals¶

resolved(value: Variant) 🔗

Emitted when the promise resolves.

rejected(reason: Variant) 🔗

Emitted when the promise rejects.

settled(state: Status, value_or_reason: Variant) 🔗

Emitted when the promise settles with either outcome.

Enumerations¶

enum Status: 🔗

Status PENDING = 0

The promise has not settled.

Status RESOLVED = 1

The promise resolved with a value.

Status REJECTED = 2

The promise rejected with a reason.

Constants¶

ERR_TIMEOUT = &"timeout" 🔗

Default rejection reason of timeout().

MAX_SYNC_SETTLEMENT_DEPTH = 8 🔗

Maximum depth of nested settlements handled in one call stack. Deeper settlements are emitted with call_deferred() to protect the stack.

Property Descriptions¶

bool is_settled 🔗

bool @is_settled_getter()

True when the promise is no longer pending.

bool is_resolved 🔗

bool @is_resolved_getter()

True when the promise resolved.

bool is_rejected 🔗

bool @is_rejected_getter()

True when the promise rejected.

Status status 🔗

Status @status_getter()

The current promise state.

Variant result 🔗

Variant @result_getter()

Alias of value.

Variant value 🔗

Variant @value_getter()

The resolved value or the rejection reason.

int id = _id_counter 🔗

Sequence number of the promise instance.

Method Descriptions¶

void _init(callback: Callable = <anonymous lambda>) 🔗

Creates a promise and calls callback with the resolve and reject callables. The callback can await. Without a callback the promise resolves with null.

GdbPromise then(on_fulfilled: Callable) 🔗

Returns a new promise that resolves with the return value of on_fulfilled, called with the resolved value. When the callback returns a promise, the new promise follows it. A rejection skips the callback and rejects the new promise with the same reason.

GdbPromise catch(callback: Callable) 🔗

Returns a new promise. When this promise rejects, callback runs with the reason and the new promise rejects with the return value of the callback. When the callback returns a promise, the new promise follows it. When this promise resolves, the new promise resolves with the same value. Note: Unlike JavaScript, catch() does not recover the chain into a resolved state.

GdbPromise finally(callback: Callable) 🔗

Calls callback at once, awaits it, and returns this promise. The method does not wait for settlement. The return value of the callback is ignored, with a warning when it is not null.

Variant await_resolved() 🔗

Waits until the promise resolves and returns the value. A rejected promise never returns from this method.

void await_settled() 🔗

Waits until the promise settles with either outcome.

Variant await_rejected() 🔗

Waits until the promise rejects and returns the reason. A resolved promise never returns from this method.

Variant await_then() 🔗

Alias of await_resolved().

Variant await_catch() 🔗

Alias of await_rejected().

void await_finally() 🔗

Alias of await_settled().

void resolve(value_: Variant = null) 🔗

Resolves the promise with value_. Does nothing after settlement.

void reject(reason: Variant = null) 🔗

Rejects the promise with reason. Does nothing after settlement.

GdbPromise new_resolved(value_: Variant = null) static 🔗

Creates a promise resolved with value_.

GdbPromise new_rejected(reason: Variant = null) static 🔗

Creates a promise rejected with reason.

GdbPromise all(promises: Array) static 🔗

Returns a promise that resolves with an array of the results of promises, in the same order, once all of them resolve. It rejects with the first rejection reason. An empty array resolves with an empty array.

GdbPromise race(promises: Array) static 🔗

Returns a promise that settles with the outcome of the first promise in promises that settles. An empty array never settles.

GdbPromise sleep(duration: float) static 🔗

Returns a promise that resolves after duration seconds.

GdbPromise timeout(duration: float, reason: Variant = &”timeout”) static 🔗

Returns a promise that rejects with reason after duration seconds.

GdbPromise to_promise(thing: Variant) static 🔗

Returns a promise for thing. A callable is called and the promise resolves with its awaited return value. A signal resolves the promise with its next emission. A promise is returned as is. Any other value becomes a resolved promise.

GdbPromise from_signals(success_signal: Signal, failure_signal: Signal = Signal()) static 🔗

Returns a promise that resolves with the first emission of success_signal or rejects with the first emission of failure_signal. Both signals must emit exactly one argument.