Panda3D

Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Friends | 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...

`#include "asyncFuture.h"`

Inheritance diagram for AsyncFuture:

## Public Types
typedef pvector< PT(AsyncFuture)> | Futures

## Public Member Functions
| AsyncFuture ()
| Initializes the future in the pending state. More...
virtual | ~AsyncFuture ()
| Destroys the future. More...
bool | add_waiting_task (AsyncTask *task)
| Indicates that the given task is waiting for this future to complete. More...
virtual bool | cancel ()
| Cancels the future. More...
bool | cancelled () const
| Returns true if the future was cancelled. More...
bool | done () const
| Returns true if the future is done or has been cancelled. More...
virtual TypeHandle | force_init_type ()
const std::string & | get_done_event () const
TypedObject * | get_result () const
| Returns this future's result. More...
void | get_result (TypedObject *&ptr, ReferenceCount *&ref_ptr) const
| Returns this future's result as a pair of TypedObject, ReferenceCount pointers. More...
virtual TypeHandle | get_type () const
virtual bool | is_task () const
void | notify_done (bool clean_exit)
| Schedules the done callbacks. More...
virtual void | output (std::ostream &out) const
void | set_done_event (const std::string &done_event)
void | set_result (const EventParameter &result)
void | set_result (std::nullptr_t)
| Sets this future's result. More...
void | set_result (TypedObject *ptr, ReferenceCount *ref_ptr)
| Sets this future's result. More...
void | set_result (TypedObject *result)
void | set_result (TypedReferenceCount *result)
void | set_result (TypedWritableReferenceCount *result)
void | wait ()
| Waits until the future is done. More...
void | wait (double timeout)
| Waits until the future is done, or until the timeout is reached. More...
Public Member Functions inherited from TypedReferenceCount
| TypedReferenceCount (const TypedReferenceCount &copy)
void | operator= (const TypedReferenceCount &copy)
Public Member Functions inherited from TypedObject
| TypedObject (const TypedObject &copy)=default
TypedObject * | as_typed_object ()
| Returns the object, upcast (if necessary) to a TypedObject pointer. More...
const TypedObject * | as_typed_object () const
| Returns the object, upcast (if necessary) to a TypedObject pointer. More...
int | get_best_parent_from_Set (const std::set< int > &) const
int | get_type_index () const
| Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. More...
bool | is_exact_type (TypeHandle handle) const
| Returns true if the current object is the indicated type exactly. More...
bool | is_of_type (TypeHandle handle) const
| Returns true if the current object is or derives from the indicated type. More...
TypedObject & | operator= (const TypedObject &copy)=default
Public Member Functions inherited from MemoryBase
void | operator delete (void *, void *)
void | operator delete (void *ptr)
void | operator delete[] (void *, void *)
void | operator delete[] (void *ptr)
void * | operator new (size_t size)
void * | operator new (size_t size, void *ptr)
void * | operator new[] (size_t size)
void * | operator new[] (size_t size, void *ptr)
Public Member Functions inherited from ReferenceCount
int | get_ref_count () const
WeakReferenceList * | get_weak_list () const
| Returns the WeakReferenceList associated with this ReferenceCount object. More...
bool | has_weak_list () const
| Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise. More...
void | local_object ()
| This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack. More...
void | ref () const
| Explicitly increments the reference count. More...
bool | ref_if_nonzero () const
| Atomically increases the reference count of this object if it is not zero. More...
bool | test_ref_count_integrity () const
| Does some easy checks to make sure that the reference count isn't completely bogus. More...
bool | test_ref_count_nonzero () const
| Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More...
virtual bool | unref () const
| Explicitly decrements the reference count. More...
bool | unref_if_one () const
| Atomically decreases the reference count of this object if it is one. More...
WeakReferenceList * | weak_ref ()
| Adds the indicated PointerToVoid as a weak reference to this object. More...
void | weak_unref ()
| Removes the indicated PointerToVoid as a weak reference to this object. More...

## Static Public Member Functions
static AsyncFuture * | gather (Futures futures)
| Creates a new future that returns `done()` when all of the contained futures are done. More...
static TypeHandle | get_class_type ()
static void | init_type ()
Static Public Member Functions inherited from TypedReferenceCount
static TypeHandle | get_class_type ()
static void | init_type ()
Static Public Member Functions inherited from TypedObject
static TypeHandle | get_class_type ()
static void | init_type ()
| This function is declared non-inline to work around a compiler bug in g++ 2.96. More...
Static Public Member Functions inherited from ReferenceCount
static TypeHandle | get_class_type ()
static void | init_type ()

## Public Attributes
| get_done_event
| Returns the event name that will be triggered when the future finishes. More...
| set_done_event
| Sets the event name that will be triggered when the future finishes. More...
Public Attributes inherited from TypedObject
| get_type
Public Attributes inherited from ReferenceCount
| get_ref_count
| Returns the current reference count. More...

## Friends
class | AsyncGatheringFuture
class | AsyncTaskChain
class | PythonTask

## 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

Definition at line 61 of file asyncFuture.h.

## Constructor & Destructor Documentation

## ◆ AsyncFuture()

AsyncFuture::AsyncFuture | ( |  | ) |
| inline

Initializes the future in the pending state.

Definition at line 17 of file asyncFuture.I.

## ◆ ~AsyncFuture()

AsyncFuture::~AsyncFuture | ( |  | ) |
| virtual

Destroys the future.

Assumes notify_done() has already been called.

Definition at line 28 of file asyncFuture.cxx.

## Member Function Documentation

## ◆ add_waiting_task()

bool AsyncFuture::add_waiting_task | ( | AsyncTask * | task | ) |

Indicates that the given task is waiting for this future to complete.

When the future is done, it will reactivate the given task. If this is called while the future is already done, schedules the task immediately. Assumes the manager's lock is not held.

Returns
  true if the future was pending, false if it was already done.

Definition at line 232 of file asyncFuture.cxx.

## ◆ cancel()

bool AsyncFuture::cancel | ( |  | ) |
| virtual

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

Reimplemented in AsyncGatheringFuture, and PreparedGraphicsObjects::EnqueuedObject.

Definition at line 56 of file asyncFuture.cxx.

References notify_done().

Referenced by AsyncGatheringFuture::cancel().

## ◆ cancelled()

bool AsyncFuture::cancelled | ( |  | ) | const
| inline

Returns true if the future was cancelled.

It is always safe to call this.

Definition at line 36 of file asyncFuture.I.

## ◆ done()

bool AsyncFuture::done | ( |  | ) | const
| inline

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

It is always safe to call this.

Definition at line 28 of file asyncFuture.I.

Referenced by AsyncGatheringFuture::cancel(), and wait().

## ◆ gather()

AsyncFuture * AsyncFuture::gather | ( | Futures | futures | ) |
| inline static

Creates a new future that returns `done()` when all of the contained futures are done.

Calling `cancel()` on the returned future will result in all contained futures that have not yet finished to be cancelled.

Definition at line 123 of file asyncFuture.I.

## ◆ get_result() [1/2]

TypedObject * AsyncFuture::get_result | ( |  | ) | const
| inline

Returns this future's result.

Can only be called if done() returns true.

Definition at line 64 of file asyncFuture.I.

## ◆ get_result() [2/2]

void AsyncFuture::get_result | ( | TypedObject *& | ptr,
|  | ReferenceCount *& | ref_ptr
| ) |  | const
| inline

Returns this future's result as a pair of TypedObject, ReferenceCount pointers.

Can only be called if done() returns true.

Definition at line 76 of file asyncFuture.I.

## ◆ notify_done()

void AsyncFuture::notify_done | ( | bool | clean_exit | ) |

Schedules the done callbacks.

Called after the future has just entered the 'done' state.

Parameters

  clean_exit | true if finished successfully, false if cancelled.

Definition at line 145 of file asyncFuture.cxx.

Referenced by cancel(), AsyncGatheringFuture::cancel(), and set_result().

## ◆ set_result() [1/2]

void AsyncFuture::set_result | ( | std::nullptr_t |  | ) |
| inline

Sets this future's result.

Can only be called if done() returns false.

Definition at line 91 of file asyncFuture.I.

## ◆ set_result() [2/2]

void AsyncFuture::set_result | ( | TypedObject * | ptr,
|  | ReferenceCount * | ref_ptr
| ) |  |

Sets this future's result.

Can only be done while the future is not done. Calling this marks the future as done and schedules the done callbacks.

This variant takes two pointers; the second one is only set if this object inherits from ReferenceCount, so that a reference can be held.

Assumes the manager's lock is *not* held.

Definition at line 189 of file asyncFuture.cxx.

References Thread::force_yield(), and notify_done().

## ◆ wait() [1/2]

void AsyncFuture::wait | ( |  | ) |

Waits until the future is done.

Definition at line 95 of file asyncFuture.cxx.

References done(), and Thread::force_yield().

## ◆ wait() [2/2]

void AsyncFuture::wait | ( | double | timeout | ) |

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

Definition at line 118 of file asyncFuture.cxx.

References done(), Thread::force_yield(), ClockObject::get_global_clock(), and ClockObject::get_real_time.

## Member Data Documentation

## ◆ get_done_event

const std::string & AsyncFuture::get_done_event
| inline

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

See set_done_event().

Definition at line 77 of file asyncFuture.h.

## ◆ set_done_event

void AsyncFuture::set_done_event
| inline

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.

Definition at line 77 of file asyncFuture.h.

The documentation for this class was generated from the following files:

- panda/src/event/asyncFuture.h
- panda/src/event/asyncFuture.cxx
- panda/src/event/asyncFuture.I