gdDocumentation0.8.0

API reference

GD.async

Entry for async work: waiting, concurrency, racing, timeouts, and cancellation. spawn starts a main-thread coroutine; CPU work belongs in each standard module's _async entry points.

A Signal saved with := keeps its completion type; reassigning a Signal of a different or unknown type is rejected. When a generic Signal is saved and awaited later, a two-value completion arrives as an Array: read result[0] and result[1].

Long GDScript yields to other work automatically, but the inside of a native method is not interrupted.

Waiting methods can be called only from functions that GDScript called. Native callbacks such as Array.map(), _init(), member initializers, and _to_string() cannot wait; adding await inside them does not make the native caller wait.

Methods

set_max_threads

set_max_threads(max: int) -> int

Set the runtime-wide managed-thread limit and return the previous value.

Parameters

NameTypeDefaultDescription
maxintRequiredRuntime-wide limit on managed threads; returns the previous limit.

Return value

int

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

The default is 10000. Exceeding the limit terminates the process, and so does lowering it below the current count. Threads created directly by external libraries are not counted.

sleep

sleep(sec: float) -> Signal

Return a signal emitted after the specified delay.

Parameters

NameTypeDefaultDescription
secfloatRequiredDuration in seconds, including fractional seconds.

Return value

Signal

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

spawn

spawn(fn: Callable) -> Signal

Start a callable as a cooperative routine on the main thread and return its completion signal. This does not move CPU-heavy script code onto another thread; use worker-backed standard APIs for blocking work.

Parameters

NameTypeDefaultDescription
fnCallableRequiredCallable to start.

Return value

Signal

A Signal carrying the callable completion.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

See also

spawn_pair

spawn_pair(fn: Callable) -> await Variant, Err

Start a callable with separate value and error completion slots.

Parameters

NameTypeDefaultDescription
fnCallableRequiredCallable to invoke; supplied arguments follow the API's callback contract.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

call_pair

call_pair(fn: Callable) -> Variant, Err

Invoke a dynamically selected function with separate result slots.

Call a dynamically selected Callable and receive its value and Err as two results.

Parameters

NameTypeDefaultDescription
fnCallableRequiredCallable to invoke; supplied arguments follow the API's callback contract.

Return value

Variant, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

all

all(signals: Array) -> await Array

Wait for supplied signals and start supplied callables, collecting completion values in the same order as the input. Completion order does not change the result positions.

Parameters

NameTypeDefaultDescription
signalsArrayRequiredSignals or callables to compose.

Return value

await Array

An array of completion values; inspect each result for its own error.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

An input that cannot be awaited becomes an Err in its result slot. The message names the position and the reason, and info.index holds the position. Prefer Callables to Signals: completion is subscribed before each Callable starts, so a result that finishes early is not lost.

See also

race

race(signals: Array) -> await int

Return the index of the first completed signal.

Parameters

NameTypeDefaultDescription
signalsArrayRequiredCompletion Signals or Callables to combine, in result order.

Return value

await int

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

with_timeout

with_timeout(signal: Signal, sec: float) -> await int

Wait for an operation or its deadline, whichever comes first.

Parameters

NameTypeDefaultDescription
signalSignalRequiredCompletion Signal of the operation to observe.
secfloatRequiredDuration in seconds, including fractional seconds.

Return value

await int

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

with_context

with_context(context: GDAsyncContext, signal: Signal) -> await Variant

Wait for an operation while observing a cancellation context. Use the same request context for operations that should stop when the caller disconnects or the deadline expires.

Parameters

NameTypeDefaultDescription
contextGDAsyncContextRequiredContext whose cancellation should be observed.
signalSignalRequiredA live completion Signal from a reference-counted operation exposing cancel(). Arbitrary object signals are not accepted.

Return value

await Variant

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

See also

with_context_pair

with_context_pair(context: GDAsyncContext, signal: Signal) -> await Variant, Err

Propagate context cancellation while preserving both result slots.

Parameters

NameTypeDefaultDescription
contextGDAsyncContextRequiredCancellation context that controls the operation lifetime.
signalSignalRequiredCompletion Signal of the operation to observe.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

context

context() -> GDAsyncContext

Create a context that shares a cancellation reason.

Parameters

No parameters.

Return value

GDAsyncContext

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.