tasks: Task creation and monitoring

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.

ADD_TASK

Name of trigger that is fired when a new task registers with the state manager.

Type:

str

REMOVE_TASK

Name of trigger that is fired when an existing task deregisters with the state manager.

Type:

str

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

Bases: 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’ implements a minimal run function which checks for termination, waits for a time step, and then calls a monitor method. To implement functionality, the ‘run’ method must be overriden. At the end of the run method, subclasses can call super().run() to hook into this functionality.

Any status updating logic should be implemented by overriding the ‘monitor’ method.

Finally, next_check can be overridden to provide alternative timetables for updating the status of tasks.

Classes deriving from ‘Job’ indirectly inherit 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().

monitor()

Experimental API . Check the status of the background process.

The task should be marked as terminated when the background process is done

run()

Experimental API . Run the task.

This method must be overridden to implement actual functionality. terminating() should be checked regularly to see whether user has requested termination.

abstract running()

Experimental API . Check if job is running.

exception JobError

Bases: RuntimeError

Generic job error.

exception JobLaunchError

Bases: JobError

Exception thrown when job launch fails.

exception JobMonitorError

Bases: JobError

Exception thrown when job status check fails.

class Task(session, id=None)

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

id

id is a unique identifier among Task instances registered with the session state manager.

Type:

readonly int

state

state is one of PENDING, RUNNING, TERMINATING TERMINATED, and FINISHED.

Type:

readonly TaskState

SESSION_ENDURING

If True, then task survives across sessions.

Type:

bool, class-level optional

SESSION_SAVE

If True, then task is saved in sessions.

Type:

bool, class-level optional

on_finish()

Experimental API . 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.

restore(*args, **kw)

Experimental API . Like start, but for restoring a task from a snapshot.

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

abstract run(*args, **kw)

Experimental API . Run the task.

This method must be overridden to implement actual functionality. terminating() should be checked regularly to see whether user has requested termination.

property session

Read-only property for session that contains this task.

start(*args, **kw)

Experimental API . Start task running.

If a keyword arguments ‘blocking’ is present and true, this method calls the instance ‘run’ method in the current thread; otherwise, it calls the instance ‘run’ method in a separate thread. The ‘blocking’ keyword is passed through, so the ‘run’ methods in derived classes will see it.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

Return type:

dict[any, any]

terminate()

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

Experimental API . Return whether task has finished.

terminating()

Experimental API . Return whether user has requested termination of this task.

class TaskState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

class Tasks(session)

Bases: StateManager

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)

Experimental API . 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.

list()

Experimental API . Return list of tasks.

Returns:

List of Task instances.

Return type:

list

reset_state(session)

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

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

property session

Read-only property for session that contains this task.

take_snapshot(session, flags)

Experimental API . 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.