motoko.task_manager

Classes

`RunList`	A `RunList` object represent a list of runs that can be await-ed
`TaskSelectionEval`
`TaskSelection`	Lazy BlackDynamite run selection.
`TaskManager`	Manages one BlackDynamite study inside a Motoko workflow.

Module Contents

class motoko.task_manager.RunList(runs: list[tuple[BlackDynamite.run_zeo.RunZEO, BlackDynamite.job.JobZEO]])

A RunList object represent a list of runs that can be await-ed until the state of all runs becomes FINISHED. Its usage is for within asynchronous routines with a sequence like:

some_runs = [...]  # list of run objects
finished_runs = await RunList(some_runs)

Some runs are typically produced by interaction with a workflow:

created = await task_manager.createTask(param1=value1, param2=value2)

runs

class motoko.task_manager.TaskSelectionEval(func: collections.abc.Callable[[], Any])

func

class motoko.task_manager.TaskSelection(constraints: list[str], selector: Any, base: Any, study: str)

Lazy BlackDynamite run selection.

TaskManager.select returns this object instead of just a list. It can be used as a normal iterable/list-like value, called explicitly, converted to bool, or awaited. Awaiting polls the underlying BlackDynamite selection until at least one run matches.

matching_condition: collections.abc.Callable[Ellipsis, bool] | None = None

constraints

base

selector

study

exec() → list[BlackDynamite.run_zeo.RunZEO]

all(*args: Any) → TaskSelectionEval: Wait until all selected runs satisfy one set of constraints.

class motoko.task_manager.TaskManager(workflow: motoko.workflow.Workflow, study: str)

Manages one BlackDynamite study inside a Motoko workflow.

A task manager for a BD study named solve uses the directory <workflow-dir>/solve. This directory contains the study’s configuration file bd.yaml, the Python script doIt.py that contains the code to be executed, and launch.sh that executes doIt.py.

The task manager deliberately keeps BlackDynamite concepts visible: jobs describe input parameter combinations, runs describe the execution (e.g. the used software), and run state is the coordination signal used by the workflow.

Lifecycle within a workflow:

Construction reads the task-manager entry from motoko.yaml and the study’s bd.yaml. The job_space and run_params entries in bd.yaml become defaults for every task created by this manager.
bd_study.create_bd_study resets and initializes the underlying BlackDynamite database and starts its ZEO server.
base lazily connects to the BlackDynamite Base for the study. The connection is cached so repeated selections and task creation share the same base object.
createTask creates new runs/jobs.

Run execution is handled externally by the BlackDynamite launcher daemons, which Motoko starts when the workflow is created.

workflow

study

config

selector = None

connect() → BlackDynamite.base_zeo.BaseZEO

property base: BlackDynamite.base_zeo.BaseZEO: Return a cached BlackDynamite Base connection for this study.

property bd_config: dict[str, Any]: Load the study-local bd.yaml schema and defaults.

property study_dir: str

property bd_dir: str

createTask(run_params: dict[str, Any] | None = None, commit: bool = False, **kwargs: Any) → RunList

Create BlackDynamite runs for the current workflow run.

The current workflow.run_name is mandatory. It is copied onto each run so selections can isolate one logical workflow execution from old runs in the same study. Motoko also records the Python caller name in the run’s event_name field, making it easier to inspect which workflow action created each run.

Parameters:

run_params – Optional run parameters stored on every created run. They are merged with the default run_params from bd.yaml.
commit – True immediately forwards to the underlying BlackDynamite create/select calls to update the database. False leaves transaction handling to Motoko’s transaction wrapper.
**kwargs – Job parameters. They are merged with the manager’s default job_space from bd.yaml and expanded through BlackDynamite’s parameter-space machinery. List-valued parameters can create several jobs/runs.

Returns:

A task_manager.RunList object containing the created (run, job) pairs. The returned object is awaitable; if createTask is called with the await decorator, it waits until all runs reach the FINISHED state.

Raises:

RuntimeError – If workflow.run_name is not set.

select(constraints: str | list[str] | None = None) → TaskSelection

Return runs matching BlackDynamite constraints as a TaskSelection object.

The constraints may be None, a single constraint string, or a list of constraint strings. When workflow.run_name is set, Motoko appends run_name = <value> so orchestration logic only handles runs belonging to the current workflow execution.