Panda3D
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
AsyncFuture Class Reference

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. More...

Inheritance diagram for AsyncFuture:
TypedReferenceCount TypedObject ReferenceCount AsyncTask AnimateVerticesRequest AsyncTaskPause AsyncTaskSequence AudioLoadRequest ModelFlattenRequest ModelLoadRequest ModelSaveRequest PythonTask TextureReloadRequest

Public Member Functions

 __init__ ()
 Initializes the future in the pending state. More...
 
 __init__ (const AsyncFuture)
 
object addDoneCallback (object fn)
 
bool cancel ()
 Cancels the future. More...
 
bool cancelled ()
 Returns true if the future was cancelled. More...
 
bool done ()
 Returns true if the future is done or has been cancelled. More...
 
str getDoneEvent ()
 Returns the event name that will be triggered when the future finishes. More...
 
 output (Ostream out)
 
object result (object timeout)
 
 setDoneEvent (str done_event)
 Sets the event name that will be triggered when the future finishes. More...
 
 setResult (const EventParameter result)
 
 setResult (TypedObject result)
 
 setResult (TypedReferenceCount result)
 
 setResult (TypedWritableReferenceCount result)
 
 setResult (nullptr_t)
 Sets this future's result. More...
 
 wait ()
 Waits until the future is done. More...
 
 wait (double timeout)
 Waits until the future is done, or until the timeout is reached. More...
 
- Public Member Functions inherited from TypedObject
TypeHandle getType ()
 
int getTypeIndex ()
 Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. More...
 
bool isExactType (TypeHandle handle)
 Returns true if the current object is the indicated type exactly. More...
 
bool isOfType (TypeHandle handle)
 Returns true if the current object is or derives from the indicated type. More...
 
- Public Member Functions inherited from ReferenceCount
int getRefCount ()
 Returns the current reference count. More...
 
 ref ()
 Explicitly increments the reference count. More...
 
bool testRefCountIntegrity ()
 Does some easy checks to make sure that the reference count isn't completely bogus. More...
 
bool testRefCountNonzero ()
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More...
 
bool unref ()
 Explicitly decrements the reference count. More...
 

Static Public Member Functions

static object __await__ ()
 
static object __iter__ ()
 
static object gather (object args)
 
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedReferenceCount
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedObject
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from ReferenceCount
static TypeHandle getClassType ()
 

Public Attributes

const String done_event
 Returns the event name that will be triggered when the future finishes. More...
 
- Public Attributes inherited from TypedObject
TypeHandle type
 Returns the TypeHandle representing this object's type. More...
 
- Public Attributes inherited from ReferenceCount
int ref_count
 The current reference count. More...
 

Detailed Description

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 set_result(), 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.

Since
1.10.0

Member Function Documentation

◆ __await__()

static object __await__ ( )
static

◆ __init__() [1/2]

__init__ ( )

Initializes the future in the pending state.

◆ __init__() [2/2]

__init__ ( const  AsyncFuture)

◆ __iter__()

static object __iter__ ( )
static

◆ addDoneCallback()

object addDoneCallback ( object  fn)

◆ cancel()

bool cancel ( )

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 cancelled ( )

Returns true if the future was cancelled.

It is always safe to call this.

◆ done()

bool done ( )

Returns true if the future is done or has been cancelled.

It is always safe to call this.

◆ gather()

static object gather ( object  args)
static

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getDoneEvent()

str getDoneEvent ( )

Returns the event name that will be triggered when the future finishes.

See set_done_event().

◆ output()

output ( Ostream  out)

◆ result()

object result ( object  timeout)

◆ setDoneEvent()

setDoneEvent ( str  done_event)

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() [1/5]

setResult ( const EventParameter  result)

◆ setResult() [2/5]

setResult ( TypedObject  result)

◆ setResult() [3/5]

setResult ( TypedReferenceCount  result)

◆ setResult() [4/5]

setResult ( TypedWritableReferenceCount  result)

◆ setResult() [5/5]

setResult ( nullptr_t  )

Sets this future's result.

Can only be called if done() returns false.

◆ wait() [1/2]

wait ( )

Waits until the future is done.

◆ wait() [2/2]

wait ( double  timeout)

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

Member Data Documentation

◆ done_event

const String done_event

Returns the event name that will be triggered when the future finishes.

See set_done_event().