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(max: int) -> intsleep(sec: float) -> Signalspawn(fn: Callable) -> Signalspawn_pair(fn: Callable) -> await Variant, Errcall_pair(fn: Callable) -> Variant, Errall(signals: Array) -> await Arrayrace(signals: Array) -> await intwith_timeout(signal: Signal, sec: float) -> await intwith_context(context: GDAsyncContext, signal: Signal) -> await Variantwith_context_pair(context: GDAsyncContext, signal: Signal) -> await Variant, Errcontext() -> GDAsyncContext
set_max_threads
set_max_threads(max: int) -> intSet the runtime-wide managed-thread limit and return the previous value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
max | int | Required | Runtime-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) -> SignalReturn a signal emitted after the specified delay.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sec | float | Required | Duration 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) -> SignalStart 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
| Name | Type | Default | Description |
|---|---|---|---|
fn | Callable | Required | Callable 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, ErrStart a callable with separate value and error completion slots.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
fn | Callable | Required | Callable 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, ErrInvoke a dynamically selected function with separate result slots.
Call a dynamically selected Callable and receive its value and Err as two results.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
fn | Callable | Required | Callable 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 ArrayWait 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
| Name | Type | Default | Description |
|---|---|---|---|
signals | Array | Required | Signals 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 intReturn the index of the first completed signal.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
signals | Array | Required | Completion 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 intWait for an operation or its deadline, whichever comes first.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
signal | Signal | Required | Completion Signal of the operation to observe. |
sec | float | Required | Duration 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 VariantWait 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
| Name | Type | Default | Description |
|---|---|---|---|
context | GDAsyncContext | Required | Context whose cancellation should be observed. |
signal | Signal | Required | A 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, ErrPropagate context cancellation while preserving both result slots.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
context | GDAsyncContext | Required | Cancellation context that controls the operation lifetime. |
signal | Signal | Required | Completion 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() -> GDAsyncContextCreate 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.