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

This class represents a concrete task performed by an AsyncManager. More...

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

Public Types

enum  DoneStatus {
  DS_done = 0, DS_cont = 1, DS_again = 2, DS_pickup = 3,
  DS_exit = 4, DS_pause = 5, DS_interrupt = 6, DS_await = 7
}
 
enum  State {
  S_inactive = 0, S_active = 1, S_servicing = 2, S_servicing_removed = 3,
  S_sleeping = 4, S_active_nested = 5, S_awaiting = 6
}
 

Public Member Functions

 __init__ (const AsyncTask)
 
 clearDelay ()
 Removes any delay specified for the task. More...
 
 clearName ()
 Resets the task's name to empty. More...
 
double getAverageDt ()
 Returns the average amount of time elapsed during each of the task's previous run cycles, in seconds. More...
 
double getDelay ()
 Returns the delay value that has been set via set_delay, if any. More...
 
double getDt ()
 Returns the amount of time elapsed during the task's previous run cycle, in seconds. More...
 
int getElapsedFrames ()
 Returns the number of frames that have elapsed since the task was started, according to the task manager's clock. More...
 
double getElapsedTime ()
 Returns the amount of time that has elapsed since the task was started, according to the task manager's clock. More...
 
AsyncTaskManager getManager ()
 Returns the AsyncTaskManager that this task is active on. More...
 
double getMaxDt ()
 Returns the maximum amount of time elapsed during any one of the task's previous run cycles, in seconds. More...
 
str getNamePrefix ()
 Returns the initial part of the name, up to but not including any trailing digits following a hyphen or underscore. More...
 
int getPriority ()
 Returns the task's current priority value. More...
 
int getSort ()
 Returns the task's current sort value. More...
 
int getStartFrame ()
 Returns the frame number at which the task was started, according to the task manager's clock. More...
 
double getStartTime ()
 Returns the time at which the task was started, according to the task manager's clock. More...
 
AsyncTask::State getState ()
 Returns the current state of the task. More...
 
str getTaskChain ()
 Returns the AsyncTaskChain on which this task will be running. More...
 
AtomicAdjust::Integer getTaskId ()
 Returns a number guaranteed to be unique for each different AsyncTask object in the universe. More...
 
double getWakeTime ()
 If this task has been added to an AsyncTaskManager with a delay in effect, this returns the time at which the task is expected to awaken. More...
 
bool hasDelay ()
 Returns true if a delay has been set for this task via set_delay(), or false otherwise. More...
 
bool isAlive ()
 Returns true if the task is currently active or sleeping on some task chain, meaning that it will be executed in its turn, or false if it is not active. More...
 
 output (Ostream out)
 
 recalcWakeTime ()
 If the task is currently sleeping on a task chain, this resets its wake time to the current time + get_delay(). More...
 
bool remove ()
 Removes the task from its active manager, if any, and makes the state S_inactive (or possible S_servicing_removed). More...
 
 setDelay (double delay)
 Specifies the amount of time, in seconds, by which this task will be delayed after it has been added to the AsyncTaskManager. More...
 
 setDoneEvent (str done_event)
 Sets the event name that will be triggered when the task finishes. More...
 
 setName (str name)
 
 setPriority (int priority)
 Specifies a priority value for this task. More...
 
 setSort (int sort)
 Specifies a sort value for this task. More...
 
 setTaskChain (str chain_name)
 Specifies the AsyncTaskChain on which this task will be running. More...
 
- Public Member Functions inherited from AsyncFuture
 __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...
 
- Public Member Functions inherited from Namable
 __init__ (const Namable)
 
 __init__ (str initial_name)
 
 clearName ()
 Resets the Namable's name to empty. More...
 
str getName ()
 
bool hasName ()
 Returns true if the Namable has a nonempty name set, false if the name is empty. More...
 
 output (Ostream out)
 Outputs the Namable. More...
 
 setName (str name)
 

Static Public Member Functions

static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from AsyncFuture
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 ()
 
- Static Public Member Functions inherited from Namable
static TypeHandle getClassType ()
 

Public Attributes

bool alive
 Returns true if the task is currently active or sleeping on some task chain, meaning that it will be executed in its turn, or false if it is not active. More...
 
double average_dt
 Returns the average amount of time elapsed during each of the task's previous run cycles, in seconds. More...
 
const String done_event
 ** More...
 
double dt
 Returns the amount of time elapsed during the task's previous run cycle, in seconds. More...
 
AtomicAdjust::Integer id
 This is a number guaranteed to be unique for each different AsyncTask object in the universe. More...
 
AsyncTaskManager manager
 Returns the AsyncTaskManager that this task is active on. More...
 
double max_dt
 Returns the maximum amount of time elapsed during any one of the task's previous run cycles, in seconds. More...
 
const String name
 The name of this task. More...
 
int priority
 Returns the task's current priority value. More...
 
int sort
 Returns the task's current sort value. More...
 
AsyncTask::State state
 Returns the current state of the task. More...
 
const String task_chain
 Returns the AsyncTaskChain on which this task will be running. More...
 
- Public Attributes inherited from AsyncFuture
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...
 
- Public Attributes inherited from Namable
const String name
 

Detailed Description

This class represents a concrete task performed by an AsyncManager.

Normally, you would subclass from this class, and override do_task(), to define the functionality you wish to have the task perform.

Member Enumeration Documentation

◆ DoneStatus

enum DoneStatus
Enumerator
DS_done 

normal task completion

DS_cont 

run task again next epoch

DS_again 

start the task over from the beginning

DS_pickup 

run task again this frame, if frame budget allows

DS_exit 

stop the enclosing sequence

DS_pause 

pause, then exit (useful within a sequence)

DS_interrupt 

interrupt the task manager, but run task again

DS_await 

await a different task's completion

◆ State

enum State
Enumerator
S_inactive 
S_active 
S_servicing 
S_servicing_removed 

Still servicing, but wants removal from manager.

S_sleeping 
S_active_nested 

active within a sequence.

S_awaiting 

Waiting for a dependent task to complete.

Member Function Documentation

◆ __init__()

__init__ ( const  AsyncTask)

◆ clearDelay()

clearDelay ( )

Removes any delay specified for the task.

The next time the task is added to the queue, it will run immediately. This does not affect the task's wake time if it has already been added to the queue.

◆ clearName()

clearName ( )

Resets the task's name to empty.

◆ getAverageDt()

double getAverageDt ( )

Returns the average amount of time elapsed during each of the task's previous run cycles, in seconds.

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getDelay()

double getDelay ( )

Returns the delay value that has been set via set_delay, if any.

◆ getDt()

double getDt ( )

Returns the amount of time elapsed during the task's previous run cycle, in seconds.

◆ getElapsedFrames()

int getElapsedFrames ( )

Returns the number of frames that have elapsed since the task was started, according to the task manager's clock.

It is only valid to call this if the task's status is not S_inactive.

◆ getElapsedTime()

double getElapsedTime ( )

Returns the amount of time that has elapsed since the task was started, according to the task manager's clock.

It is only valid to call this if the task's status is not S_inactive.

◆ getManager()

AsyncTaskManager getManager ( )

Returns the AsyncTaskManager that this task is active on.

This will be NULL if the state is S_inactive.

◆ getMaxDt()

double getMaxDt ( )

Returns the maximum amount of time elapsed during any one of the task's previous run cycles, in seconds.

◆ getNamePrefix()

str getNamePrefix ( )

Returns the initial part of the name, up to but not including any trailing digits following a hyphen or underscore.

◆ getPriority()

int getPriority ( )

Returns the task's current priority value.

See set_priority().

◆ getSort()

int getSort ( )

Returns the task's current sort value.

See set_sort().

◆ getStartFrame()

int getStartFrame ( )

Returns the frame number at which the task was started, according to the task manager's clock.

It is only valid to call this if the task's status is not S_inactive.

◆ getStartTime()

double getStartTime ( )

Returns the time at which the task was started, according to the task manager's clock.

It is only valid to call this if the task's status is not S_inactive.

◆ getState()

AsyncTask::State getState ( )

Returns the current state of the task.

◆ getTaskChain()

str getTaskChain ( )

Returns the AsyncTaskChain on which this task will be running.

Each task chain runs tasks independently of the others.

◆ getTaskId()

AtomicAdjust::Integer getTaskId ( )

Returns a number guaranteed to be unique for each different AsyncTask object in the universe.

◆ getWakeTime()

double getWakeTime ( )

If this task has been added to an AsyncTaskManager with a delay in effect, this returns the time at which the task is expected to awaken.

It has no meaning if the task has not yet been added to a queue, or if there was no delay in effect at the time the task was added.

If the task's status is not S_sleeping, this returns 0.0.

◆ hasDelay()

bool hasDelay ( )

Returns true if a delay has been set for this task via set_delay(), or false otherwise.

◆ isAlive()

bool isAlive ( )

Returns true if the task is currently active or sleeping on some task chain, meaning that it will be executed in its turn, or false if it is not active.

If the task has recently been removed while it is in the middle of execution, this will return false, because the task will not run again once it finishes.

◆ output()

output ( Ostream  out)

◆ recalcWakeTime()

recalcWakeTime ( )

If the task is currently sleeping on a task chain, this resets its wake time to the current time + get_delay().

It is as if the task had suddenly returned DS_again. The task will sleep for its current delay seconds before running again. This method may therefore be used to make the task wake up sooner or later than it would have otherwise.

If the task is not already sleeping, this method has no effect.

◆ remove()

bool remove ( )

Removes the task from its active manager, if any, and makes the state S_inactive (or possible S_servicing_removed).

This is a no-op if the state is already S_inactive.

◆ setDelay()

setDelay ( double  delay)

Specifies the amount of time, in seconds, by which this task will be delayed after it has been added to the AsyncTaskManager.

At least the specified amount of time (and possibly more) will elapse before the task begins.

You may specify a delay of 0.0 to guarantee that the task will run in the next epoch following the one in which it is added.

Setting this value after the task has already been added will not affect the task's wake time; it will only affect the task if it is re-added to the queue in the future, for instance if the task returns DS_again. However, see recalc_wake_time() if you wish to apply the delay effect immediately.

◆ setDoneEvent()

setDoneEvent ( str  done_event)

Sets the event name that will be triggered when the task finishes.

This should only be called before the task has been started, or after it has finished and before it is about to be restarted (i.e. when get_state() returns S_inactive).

◆ setName()

setName ( str  name)

◆ setPriority()

setPriority ( int  priority)

Specifies a priority value for this task.

In general, tasks with a higher priority value are executed before tasks with a lower priority value (but only for tasks with the same sort value).

Unlike the sort value, tasks with different priorities may execute at the same time, if the AsyncTaskManager has more than one thread servicing tasks.

Also see AsyncTaskChain::set_timeslice_priority(), which changes the meaning of this value. In the default mode, when the timeslice_priority flag is false, all tasks always run once per epoch, regardless of their priority values (that is, the priority controls the order of the task execution only, not the number of times it runs). On the other hand, if you set the timeslice_priority flag to true, then changing a task's priority has an effect on the number of times it runs.

◆ setSort()

setSort ( int  sort)

Specifies a sort value for this task.

Within a given AsyncTaskManager, all of the tasks with a given sort value are guaranteed to be completed before any tasks with a higher sort value are begun.

To put it another way, two tasks might execute in parallel with each other only if they both have the same sort value. Tasks with a lower sort value are executed first.

This is different from the priority, which makes no such exclusion guarantees.

◆ setTaskChain()

setTaskChain ( str  chain_name)

Specifies the AsyncTaskChain on which this task will be running.

Each task chain runs tasks independently of the others.

Member Data Documentation

◆ alive

bool alive

Returns true if the task is currently active or sleeping on some task chain, meaning that it will be executed in its turn, or false if it is not active.

If the task has recently been removed while it is in the middle of execution, this will return false, because the task will not run again once it finishes.

◆ average_dt

double average_dt

Returns the average amount of time elapsed during each of the task's previous run cycles, in seconds.

◆ done_event

const String done_event

**

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

◆ dt

double dt

Returns the amount of time elapsed during the task's previous run cycle, in seconds.

◆ id

AtomicAdjust::Integer id

This is a number guaranteed to be unique for each different AsyncTask object in the universe.

◆ manager

Returns the AsyncTaskManager that this task is active on.

This will be NULL if the state is S_inactive.

◆ max_dt

double max_dt

Returns the maximum amount of time elapsed during any one of the task's previous run cycles, in seconds.

◆ name

const String name

The name of this task.

◆ priority

int priority

Returns the task's current priority value.

See set_priority().

◆ sort

int sort

Returns the task's current sort value.

See set_sort().

◆ state

Returns the current state of the task.

◆ task_chain

const String task_chain

Returns the AsyncTaskChain on which this task will be running.

Each task chain runs tasks independently of the others.