panda3d.core.AsyncFuture

class AsyncFuture

Bases: TypedReferenceCount

This class represents a thread-safe handle to a promised future result of an asynchronous operation, providing methods to query its status and result as well as register callbacks for this future’s completion.

An AsyncFuture can be awaited from within a coroutine or task. It keeps track of tasks waiting for this future and automatically reactivates them upon this future’s completion.

A task itself is also a subclass of AsyncFuture. Other subclasses are not generally necessary, except to override the function of cancel().

Until the future is done, it is “owned” by the resolver thread, though it’s still legal for other threads to query its state. When the resolver thread resolves this future using setResult(), or any thread calls cancel(), it instantly enters the “done” state, after which the result becomes a read-only field that all threads can access.

When the future returns true for done(), a thread can use cancelled() to determine whether the future was cancelled or get_result() to access the result of the operation. Not all operations define a meaningful result value, so some will always return nullptr.

In Python, the cancelled(), wait() and get_result() methods are wrapped up into a single result() method which waits for the future to complete before either returning the result or throwing an exception if the future was cancelled. However, it is preferable to use the await keyword when running from a coroutine, which only suspends the current task and not the entire thread.

This API aims to mirror and be compatible with Python’s Future class.

New in version 1.10.0.

Inheritance diagram

Inheritance diagram of AsyncFuture

__init__() → None

Initializes the future in the pending state.

__init__(param0: AsyncFuture) → None
addDoneCallback(fn: object) → object
cancel() → bool

Cancels the future. Returns true if it was cancelled, or false if the future was already done. Either way, done() will return true after this call returns.

In the case of a task, this is equivalent to remove().

cancelled() → bool

Returns true if the future was cancelled. It is always safe to call this.

done() → bool

Returns true if the future is done or has been cancelled. It is always safe to call this.

property done_event
Getter

Returns the event name that will be triggered when the future finishes. See setDoneEvent().

Setter

Sets the event name that will be triggered when the future finishes. Will not be triggered if the future is cancelled, but it will be triggered for a coroutine task that exits with an exception.

Return type

string

static gather(args: object) → object
static getClassType() → TypeHandle
Return type

TypeHandle

getDoneEvent() → str

Returns the event name that will be triggered when the future finishes. See setDoneEvent().

output(out: ostream) → None
result(timeout: object) → object
setDoneEvent(done_event: str) → None

Sets the event name that will be triggered when the future finishes. Will not be triggered if the future is cancelled, but it will be triggered for a coroutine task that exits with an exception.

setResult(result: EventParameter) → None
setResult(result: TypedObject) → None
setResult(result: TypedReferenceCount) → None
setResult(result: TypedWritableReferenceCount) → None
setResult(param0: nullptr_t) → None

Sets this future’s result. Can only be called if done() returns false.

wait() → None

Waits until the future is done.

wait(timeout: float) → None

Waits until the future is done, or until the timeout is reached.