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

class Job(*args, **kw)

Bases: chimerax.core.tasks.Task

‘Job’ is a long-running task.

A ‘Job’ instance is a ChimeraX 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 session State 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, not run().

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 methods launch(), running() and monitor() to initiate and check status of the background process. Timing of the checks are handled by the next_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: chimerax.core.tasks.JobError

Exception thrown when job launch fails.

exception JobMonitorError

Bases: chimerax.core.tasks.JobError

Exception thrown when job status check fails.

class Task(session, id=None, **kw)

Bases: chimerax.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 session State should be defined so that saving and restoring of scenes and sessions work properly, and the run() 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 of PENDING, RUNNING, TERMINATING TERMINATED, and FINISHED.
SESSION_ENDURING (bool, class-level optional) If True, then task survives across sessions.
SESSION_SAVE (bool, class-level optional) If True, then task is 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, first=False)

Bases: chimerax.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.

add(task)

Register task with state manager.

Parameters:

task : Task instances

A newly created task.

find_by_class(cls)

Return a list of tasks of the given class.

All tasks that match cls as defined by isinstance() 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.

list()

Return list of tasks.

Returns:

list

List of Task instances.

remove(task)

Deregister task with state manager.

Parameters:

task_list : list of Task instances

List of registered tasks.

reset_state(session)

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.

static restore_snapshot(session, data)

Restore state of running tasks.

Overrides State default method to restore 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__.

data : any

Data saved by state manager during take_snapshot().

take_snapshot(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 chimerax.core.session for more details.

update_state(task, new_state)

Update the state for the given task.

Parameters:

task : Task instance

Task whose state just changed

new_state : str

New state of the task (one of PENDING, RUNNING, TERMINATING or FINISHED).