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

#include "asyncTask.h"

Inheritance diagram for AsyncTask:

Public Types
enum	DoneStatus { DS_done, DS_cont, DS_again, DS_pickup, DS_exit, DS_pause, DS_interrupt }
enum	State { S_inactive, S_active, S_servicing, S_servicing_removed, S_sleeping, S_active_nested }
Public Member Functions
	AsyncTask (const string &name=string())
void	clear_delay ()
	Removes any delay specified for the task.
void	clear_name ()
	Resets the task's name to empty.
virtual TypeHandle	force_init_type ()
double	get_average_dt () const
	Returns the average amount of time elapsed during each of the task's previous run cycles, in seconds.
double	get_delay () const
	Returns the delay value that has been set via set_delay, if any.
const string &	get_done_event () const
	Returns the event name that will be triggered when the task finishes.
double	get_dt () const
	Returns the amount of time elapsed during the task's previous run cycle, in seconds.
int	get_elapsed_frames () const
	Returns the number of frames that have elapsed since the task was started, according to the task manager's clock.
double	get_elapsed_time () const
	Returns the amount of time that has elapsed since the task was started, according to the task manager's clock.
AsyncTaskManager *	get_manager () const
	Returns the AsyncTaskManager that this task is active on.
double	get_max_dt () const
	Returns the maximum amount of time elapsed during any one of the task's previous run cycles, in seconds.
string	get_name_prefix () const
	Returns the initial part of the name, up to but not including any trailing digits following a hyphen or underscore.
int	get_priority () const
	Returns the task's current priority value.
int	get_sort () const
	Returns the task's current sort value.
int	get_start_frame () const
	Returns the frame number at which the task was started, according to the task manager's clock.
double	get_start_time () const
	Returns the time at which the task was started, according to the task manager's clock.
State	get_state () const
	Returns the current state of the task.
const string &	get_task_chain () const
	Returns the AsyncTaskChain on which this task will be running.
AtomicAdjust::Integer	get_task_id () const
	Returns a number guaranteed to be unique for each different AsyncTask object in the universe.
virtual TypeHandle	get_type () const
double	get_wake_time () const
	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.
bool	has_delay () const
	Returns true if a delay has been set for this task via set_delay(), or false otherwise.
bool	is_alive () const
	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.
virtual void	output (ostream &out) const
	Outputs the Namable.
void	recalc_wake_time ()
	If the task is currently sleeping on a task chain, this resets its wake time to the current time + get_delay().
void	remove ()
	Removes the task from its active manager, if any, and makes the state S_inactive (or possible S_servicing_removed).
void	set_delay (double delay)
	Specifies the amount of time, in seconds, by which this task will be delayed after it has been added to the AsyncTaskManager.
void	set_done_event (const string &done_event)
	Sets the event name that will be triggered when the task finishes.
void	set_name (const string &name)
void	set_priority (int priority)
	Specifies a priority value for this task.
void	set_sort (int sort)
	Specifies a sort value for this task.
void	set_task_chain (const string &chain_name)
	Specifies the AsyncTaskChain on which this task will be running.
Static Public Member Functions
static TypeHandle	get_class_type ()
static void	init_type ()
Protected Member Functions
virtual DoneStatus	do_task ()
	Override this function to do something useful for the task.
virtual bool	is_runnable ()
	Override this function to return true if the task can be successfully executed, false if it cannot.
void	jump_to_task_chain (AsyncTaskManager *manager)
	Switches the AsyncTask to its new task chain, named by _chain_name.
DoneStatus	unlock_and_do_task ()
	Called by the AsyncTaskManager to actually run the task.
virtual void	upon_birth (AsyncTaskManager *manager)
	Override this function to do something useful when the task has been added to the active queue.
virtual void	upon_death (AsyncTaskManager *manager, bool clean_exit)
	Override this function to do something useful when the task has been removed from the active queue.
Protected Attributes
AsyncTaskChain *	_chain
string	_chain_name
double	_delay
string	_done_event
double	_dt
bool	_has_delay
AsyncTaskManager *	_manager
double	_max_dt
int	_num_frames
int	_priority
Thread *	_servicing_thread
int	_sort
int	_start_frame
double	_start_time
State	_state
AtomicAdjust::Integer	_task_id
PStatCollector	_task_pcollector
double	_total_dt
double	_wake_time
Static Protected Attributes
static AtomicAdjust::Integer	_next_task_id
static PStatCollector	_show_code_pcollector
Friends
class	AsyncTaskChain
class	AsyncTaskManager
class	AsyncTaskSequence

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.

Definition at line 43 of file asyncTask.h.

Member Function Documentation

void AsyncTask::clear_delay ( ) [inline]

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.

Definition at line 100 of file asyncTask.I.

void AsyncTask::clear_name ( ) [inline]

Resets the task's name to empty.

Reimplemented from Namable.

Definition at line 163 of file asyncTask.I.

AsyncTask::DoneStatus AsyncTask::do_task ( ) [protected, virtual]

Override this function to do something useful for the task.

The return value should be one of:

DS_done: the task is finished, remove from active and throw the done event.

DS_cont: the task has more work to do, keep it active and call this function again in the next epoch.

DS_again: like DS_cont, but next time call the function from the beginning, almost as if it were freshly added to the task manager. The task's get_start_time() will be reset to now, and its get_elapsed_time() will be reset to 0. If the task has a set_delay(), it will wait again for that amount of time to elapse before restarting. Timing accounting, however, is not reset.

DS_pickup: like DS_cont, but if the task chain has a frame budget and that budget has not yet been met, re-run the task again without waiting for the next frame. Otherwise, run it next epoch as usual.

DS_exit: stop the task, and stop the enclosing sequence too. Outside of a sequence, this is the same as DS_done.

DS_pause: delay the task for set_delay() seconds, then stop it. This is only useful within a sequence.

DS_interrupt: Interrupt the whole AsyncTaskManager. The task will continue again next epoch, as if it had returned DS_cont.

This function is called with the lock *not* held.

Reimplemented in ModelSaveRequest, GenericAsyncTask, ModelLoadRequest, AudioLoadRequest, AsyncTaskSequence, AnimateVerticesRequest, TextureReloadRequest, ModelFlattenRequest, BindAnimRequest, and AsyncTaskPause.

Definition at line 528 of file asyncTask.cxx.

Referenced by unlock_and_do_task().

double AsyncTask::get_average_dt ( ) const [inline]

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

Definition at line 302 of file asyncTask.I.

Referenced by AsyncTaskChain::filter_timeslice_priority(), and AsyncTaskChain::write_task_line().

double AsyncTask::get_delay ( ) const [inline]

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

Definition at line 123 of file asyncTask.I.

Referenced by AsyncTaskChain::do_add().

const string & AsyncTask::get_done_event ( ) const [inline]

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

See set_done_event().

Definition at line 235 of file asyncTask.I.

double AsyncTask::get_dt ( ) const [inline]

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

Definition at line 280 of file asyncTask.I.

int AsyncTask::get_elapsed_frames ( ) const

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.

Definition at line 177 of file asyncTask.cxx.

double AsyncTask::get_elapsed_time ( ) const

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.

Definition at line 160 of file asyncTask.cxx.

AsyncTaskManager * AsyncTask::get_manager ( ) const [inline]

Returns the AsyncTaskManager that this task is active on.

This will be NULL if the state is S_inactive.

Definition at line 61 of file asyncTask.I.

double AsyncTask::get_max_dt ( ) const [inline]

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

Definition at line 291 of file asyncTask.I.

string AsyncTask::get_name_prefix ( ) const

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

Definition at line 249 of file asyncTask.cxx.

int AsyncTask::get_priority ( ) const [inline]

Returns the task's current priority value.

See set_priority().

Definition at line 209 of file asyncTask.I.

Referenced by GraphicsStateGuardian::async_reload_texture().

int AsyncTask::get_sort ( ) const [inline]

Returns the task's current sort value.

See set_sort().

Definition at line 198 of file asyncTask.I.

Referenced by AsyncTaskChain::do_add().

int AsyncTask::get_start_frame ( ) const [inline]

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.

Definition at line 152 of file asyncTask.I.

double AsyncTask::get_start_time ( ) const [inline]

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.

Definition at line 137 of file asyncTask.I.

AsyncTask::State AsyncTask::get_state ( ) const [inline]

Returns the current state of the task.

Definition at line 22 of file asyncTask.I.

const string & AsyncTask::get_task_chain ( ) const [inline]

Returns the AsyncTaskChain on which this task will be running.

Each task chain runs tasks independently of the others.

Definition at line 186 of file asyncTask.I.

AtomicAdjust::Integer AsyncTask::get_task_id ( ) const [inline]

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

Definition at line 174 of file asyncTask.I.

double AsyncTask::get_wake_time ( ) const

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.

Definition at line 107 of file asyncTask.cxx.

bool AsyncTask::has_delay ( ) const [inline]

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

Definition at line 112 of file asyncTask.I.

Referenced by AsyncTaskChain::do_add().

bool AsyncTask::is_alive ( ) const [inline]

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.

Definition at line 37 of file asyncTask.I.

bool AsyncTask::is_runnable ( ) [protected, virtual]

Override this function to return true if the task can be successfully executed, false if it cannot.

Mainly intended as a sanity check when attempting to add the task to a task manager.

This function is called with the lock held.

Reimplemented in GenericAsyncTask, and AsyncTaskSequence.

Definition at line 484 of file asyncTask.cxx.

Referenced by AsyncTaskManager::add().

void AsyncTask::jump_to_task_chain ( AsyncTaskManager * manager ) [protected]

Switches the AsyncTask to its new task chain, named by _chain_name.

Called internally only.

Definition at line 423 of file asyncTask.cxx.

References AsyncTaskChain::do_add(), AsyncTaskManager::do_find_task_chain(), and AsyncTaskManager::do_make_task_chain().

Referenced by set_task_chain().

void AsyncTask::output ( ostream & out ) const [virtual]

Outputs the Namable.

This function simply writes the name to the output stream; most Namable derivatives will probably redefine this.

Reimplemented from Namable.

Definition at line 409 of file asyncTask.cxx.

References Namable::has_name().

void AsyncTask::recalc_wake_time ( )

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.

Definition at line 135 of file asyncTask.cxx.

void AsyncTask::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.

Definition at line 87 of file asyncTask.cxx.

References AsyncTaskManager::remove().

void AsyncTask::set_delay ( double delay ) [inline]

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.

Definition at line 86 of file asyncTask.I.

void AsyncTask::set_done_event ( const string & done_event ) [inline]

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

Definition at line 223 of file asyncTask.I.

void AsyncTask::set_priority ( 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.

Definition at line 376 of file asyncTask.cxx.

References AsyncTaskChain::do_add(), AsyncTaskManager::do_find_task_chain(), and AsyncTaskChain::do_remove().

Referenced by GraphicsStateGuardian::async_reload_texture().

void AsyncTask::set_sort ( 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.

Definition at line 324 of file asyncTask.cxx.

References AsyncTaskChain::do_add(), AsyncTaskManager::do_find_task_chain(), and AsyncTaskChain::do_remove().

void AsyncTask::set_task_chain ( const string & chain_name )

Specifies the AsyncTaskChain on which this task will be running.

Each task chain runs tasks independently of the others.

Definition at line 277 of file asyncTask.cxx.

References AsyncTaskChain::do_remove(), and jump_to_task_chain().

Referenced by Loader::load_async(), and Loader::save_async().

AsyncTask::DoneStatus AsyncTask::unlock_and_do_task ( ) [protected]

Called by the AsyncTaskManager to actually run the task.

Assumes the lock is held. See do_task().

Definition at line 442 of file asyncTask.cxx.

References MutexDirect::acquire(), AsyncTaskBase::clear_task(), do_task(), AsyncTaskManager::get_clock(), Thread::get_current_thread(), AsyncTaskBase::record_task(), and MutexDirect::release().

void AsyncTask::upon_birth ( AsyncTaskManager * manager ) [protected, virtual]

Override this function to do something useful when the task has been added to the active queue.

This function is called with the lock *not* held.

Reimplemented in GenericAsyncTask, and AsyncTaskSequence.

Definition at line 541 of file asyncTask.cxx.

Referenced by AsyncTaskManager::add().

void AsyncTask::upon_death	(	AsyncTaskManager *	manager,
		bool	clean_exit
	)		`[protected, virtual]`

Override this function to do something useful when the task has been removed from the active queue.

The parameter clean_exit is true if the task has been removed because it exited normally (returning DS_done), or false if it was removed for some other reason (e.g. AsyncTaskManager::remove()). By the time this method is called, _manager has been cleared, so the parameter manager indicates the original AsyncTaskManager that owned this task.

The normal behavior is to throw the done_event only if clean_exit is true.

This function is called with the lock *not* held.

Reimplemented in GenericAsyncTask, and AsyncTaskSequence.

Definition at line 568 of file asyncTask.cxx.

Referenced by AsyncTaskChain::cleanup_task().

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

panda/src/event/asyncTask.h
panda/src/event/asyncTask.cxx
panda/src/event/asyncTask.I

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Member Function Documentation