tasks: Task creation and monitoring¶
This module defines classes for tasks and their state manager.
Tasks are threads of execution that continue independently from the main UI thread. They can be used for web services or local computations that potentially take a while and should be done in the background to keep the UI interactive.
Attributes¶
- ADD_TASK : str
- Name of trigger that is fired when a new task registers with the state manager.
- REMOVE_TASK : str
- Name of trigger that is fired when an existing task deregisters with the state manager.
Notes¶
The Tasks
instance is a singleton per session and may be
referenced as session.tasks
. It is the state manager for
‘Task’ instances.
A Task
instance represents one thread of execution
and should be registered with ‘session.tasks’ when
instantiated and deregistered when terminated.
Session-specific triggers are fired when tasks
are registered and deregistered. To add and remove
Task
handlers, use session.trigger.add_handler
and session.trigger.delete_handler
.
-
class
Job
(*args, **kw)¶ Bases:
chimera.core.tasks.Task
‘Job’ is a long-running task.
A ‘Job’ instance is a Chimera task that invokes and monitors a long-running process. Job execution is modeled as process launch followed by multiple checks for process termination.
‘Job’ is implemented by overriding the
run()
method to launch and monitor the background process. Subclasses should override the ‘launch’ and ‘monitor’ methods to implement actual functionality.Classes deriving from ‘Job’ indirectly inherits from
Task
and should override methods to implement task-specific functionality. In particularly, methods from sessionState
should be defined so that saving and restoring of scenes and sessions work properly.Notes
start()
is still the main entry point for callers to ‘Job’ instances, notrun()
.-
exited_normally
()¶ Return whether job terminated normally.
Returns: status : bool
True if normal termination, False otherwise.
-
launch
(*args, **kw)¶ Launch the background process.
-
monitor
()¶ Check the status of the background process.
The task should be marked as terminated (using ‘update_state’) when the background process is done
-
run
(*args, **kw)¶ Launch and monitor a background process.
This method is run in the task thread (not the UI thread.
run
calls the abstract methodslaunch()
,running()
andmonitor()
to initiate and check status of the background process. Timing of the checks are handled by thenext_check()
method, which may be overridden to provide custom timing.
-
running
()¶ Check if job is running.
-
-
exception
JobError
¶ Bases:
RuntimeError
Generic job error.
-
exception
JobLaunchError
¶ Bases:
chimera.core.tasks.JobError
Exception thrown when job launch fails.
-
exception
JobMonitorError
¶ Bases:
chimera.core.tasks.JobError
Exception thrown when job status check fails.
-
class
Task
(session, id=None, **kw)¶ Bases:
chimera.core.state.State
Base class for instances of tasks.
Classes for tasks should inherit from
Task
and override methods to implement task-specific functionality. In particularly, methods from sessionState
should be defined so that saving and restoring of scenes and sessions work properly, and therun()
method should be overriden to provide actual functionality.Attributes
id (readonly int) id
is a unique identifier among Task instances registered with the session state manager.state (readonly str) state
is one ofPENDING
,RUNNING
,TERMINATING
TERMINATED
, andFINISHED
.SESSION_ENDURING (bool, class-level optional) If True, then task survives across sessions. SESSION_SKIP (bool, class-level optional) If True, then task is not saved in sessions. -
display_name
()¶ Name to display to user for this task.
This method should be overridden to return a task-specific name.
-
on_finish
()¶ Callback method executed after task thread terminates.
This callback is executed in the UI thread after the
run()
method returns. By default, it does nothing.
-
run
(*args, **kw)¶ Run the task.
This method must be overridden to implement actual functionality.
terminating()
should be checked regularly to see whether user has requested termination.
-
session
¶ Read-only property for session that contains this task.
-
start
(*args, **kw)¶ Start task running.
This method calls the instance ‘start’ method in a thread.
-
terminate
()¶ Terminate this task.
This method should be overridden to clean up task data structures. This base method should be called as the last step of task deletion.
-
terminated
()¶ Return whether task has finished.
-
terminating
()¶ Return whether user has requested termination of this task.
-
-
class
Tasks
(session)¶ Bases:
chimera.core.state.State
A per-session state manager for tasks.
Tasks
instances are per-session singletons that track tasks in the session, as well as managing saving and restoring task states for scenes and sessions.-
find_by_class
(cls)¶ Return a list of tasks of the given class.
All tasks that match
cls
as defined byisinstance()
are returned.Parameters: cls : class object
Class object used to match task instances.
-
find_by_id
(tid)¶ Return a
Task
instance with the matching identifier.Parameters: tid : int
Unique per-session identifier for a registered task.
-
remove
(task)¶ Deregister task with state manager.
Parameters: task_list : list of
Task
instancesList of registered tasks.
-
reset_state
()¶ Reset state manager to default state.
Overrides
State
default method to reset to default state. Since the default state has no running tasks, all registered tasks are terminated.
-
restore_snapshot
(phase, session, version, data)¶ Restore state of running tasks.
Overrides
State
default method to restore state of all registered running tasks.Parameters: phase : str
Restoration phase. See
chimera.core.session
for more details.session : instance of
Session
Session for which state is being saved. Should match the
session
argument given to__init__
.version : any
Version of state manager that saved the data. Used for determining how to parse the
data
argument.data : any
Data saved by state manager during
take_snapshot()
.
-
take_snapshot
(phase, session, flags)¶ Save state of running tasks.
Overrides
State
default method to save state of all registered running tasks.Parameters: session : instance of
Session
Session for which state is being saved. Should match the
session
argument given to__init__
.flags : int
Flags indicating whether snapshot is being taken to save scene or session. See
chimera.core.session
for more details.
-