The execution system

Schedule and manage MAST tasks, jump between labels, and read task-scope variables.

Overview

Execution functions are the backbone of MAST flow control. A task is a running instance of a label; multiple tasks can run concurrently within the same MAST scheduler. Tasks yield between ticks and resume from where they left off.

Key concepts:

• task_schedule — start a label as a new independent top-level task.
• sub_task_schedule — start a label as a child of the current task (cancelled when the parent ends).
• gui_sub_task_schedule — like sub_task_schedule but automatically cancelled when a new GUI page is shown.
• task_all / task_any — run multiple labels in parallel and await all or the first to finish.
• get_variable / get_shared_variable — read values from the current task scope or the shared Agent.SHARED scope.

LABEL_ALWAYS_IDLE is a sentinel label used internally to keep a task alive without advancing — you rarely call it directly.

Quick example

MAST pyMAST

== run_patrols ==
    await task_all(patrol_alpha, patrol_beta, patrol_gamma)
    log("All patrols complete.")

== timeout_wrapper ==
    await task_any(do_objective, timeout_30s)
    jump next_phase

== setup ==
    task_schedule(background_monitor)

from sbs_utils.procedural.execution import (
    task_schedule, task_all, task_any, task_cancel,
    get_variable, get_shared_variable,
)

# Fire-and-forget background task
task_schedule(background_monitor)

# Wait for all patrol tasks
promise = task_all(patrol_alpha, patrol_beta)

# Read a variable from current task scope
ship_id = get_variable("ship_id")

task_all vs task_any

Function	Resolves when
task_all	Every spawned task completes
task_any	The first spawned task completes (others are cancelled)

API

AWAIT(promise)

Wrap a promise in a non-blocking waiter.

Returns a PromiseWaiter whose done() method can be polled each tick without suspending the current task.

Parameters:

Name	Type	Description	Default
promise	Promise	The promise to wait on.	required

Returns:

Name	Type	Description
PromiseWaiter	PromiseWaiter	A waiter that reports completion without blocking.

END()

End the current task immediately.

Returns:

Name	Type	Description
PollResults	PollResults	OK_END signal consumed by the task scheduler.

LABEL()

Return the currently active label object for the running task.

Returns:

Type	Description
	MastNode | None: The active label, or None outside a task.

LABEL_ALWAYS_IDLE()

Yield OK_IDLE forever — keeps the current label alive without advancing.

Used as a sentinel label that never completes on its own.

get_shared_variable(key, default=None)

Get the value of a variable from the shared (Agent.SHARED) scope.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
default	optional	Value to return when the variable is absent. Defaults to None.	None

Returns:

Name	Type	Description
any	any	The variable value, or default.

get_variable(key, default=None)

Get the value of a variable from the current task's scope.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
default	optional	Value to return when the variable is absent. Defaults to None.	None

Returns:

Name	Type	Description
any	any	The variable value, or default.

gui_get_variable(key, defa=None)

Get a variable from the client (GUI) task's scope.

Reads from FrameContext.client_task. Comms routes run on the server task but still need to read GUI variables from the client task.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
defa	optional	Default if variable is absent. Defaults to None.	None

Returns:

Name	Type	Description
any		Variable value, or defa.

gui_set_variable(key, value=None)

Set a variable in the client (GUI) task's scope.

Writes to FrameContext.client_task. See gui_get_variable for context on why this differs from set_variable.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
value	any	Value to assign. Defaults to None.	None

Returns:

Name	Type	Description
any		The value set, or value if no client task exists.

gui_sub_task_schedule(label, data=None, var=None)

Create a new GUI sub-task and start running at the specified label.

The task is tagged end_on_new_gui so it is automatically cancelled when a new GUI page is presented to the client.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required
data	dict	Initial task variables. Defaults to None.	None
var	str	Variable name to store the created task. Defaults to None.	None

Returns:

Name	Type	Description
MastAsyncTask	MastAsyncTask	The MAST task created.

gui_task_jump(label)

Redirect the active GUI task to a new label.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to jump to.	required

jump(label)

reset the program flow to a label

Parameters:

Name	Type	Description	Default
label	str or label	The label to jump to	required

Returns:

Name	Type	Description
PollResults	PollResults	The poll results of the jump. used by the task.

labels_get_type(label_type)

Return all labels whose type or path starts with the given prefix.

Walks every label in the current story, checking the type metadata key first, then the label path attribute, then the label name.

Parameters:

Name	Type	Description	Default
label_type	str	Prefix to match, e.g. "map/" or "media/".	required

Returns:

Type	Description
	list[MastNode]: Matching label objects.

log(message, name=None, level=None, use_mast_scope=False)

Emit a log message using Python's logging module.

When use_mast_scope=True the message is formatted through the current MAST task's string formatter first (MAST exposes this as log).

Parameters:

Name	Type	Description	Default
message	str	The message to log. May contain MAST format strings when use_mast_scope=True.	required
name	str	Logger name. Defaults to None (__base_logger__).	None
level	str	Logging level string, e.g. "DEBUG", "INFO". Defaults to None (DEBUG).	None
use_mast_scope	bool	Format the message via the current MAST task. Defaults to False.	False

logger(name=None, file=None, var=None, std_err=False, level=None, format=None, file_mode='w')

Configure a named logger with one or more output handlers.

When neither file nor var is given, output goes to stderr.

Parameters:

Name	Type	Description	Default
name	str	Logger name. Defaults to None (__base_logger__).	None
file	str	Path to a log file (relative to mission dir). Defaults to None.	None
var	str	Shared variable name to receive a StringIO stream for in-memory log capture. Defaults to None.	None
std_err	bool	Add a stderr handler. Defaults to False (forced True when no file or var is supplied).	False
level	str	Logging level, e.g. "INFO", "WARNING". Defaults to None (DEBUG).	None
format	str	Python log format string. Defaults to None ("%(message)s").	None
file_mode	str	File open mode — 'w' to overwrite, 'a' to append. Defaults to 'w'.	'w'

mast_log(message, name=None, level=None, use_mast_scope=True)

Generate a log message formatted through the current MAST task scope.

Convenience wrapper around log with use_mast_scope=True.

Parameters:

Name	Type	Description	Default
message	str	The message to log. May contain MAST format strings.	required
name	str	Logger name. Defaults to None.	None
level	str	Logging level string. Defaults to None.	None

metadata_get_value(k, defa=None)

Return a metadata value stored on the active label object.

Label metadata is set via MAST inventory calls on the label node itself.

Parameters:

Name	Type	Description	Default
k	str	Metadata key to look up.	required
defa	optional	Value returned when key is absent. Defaults to None.	None

Returns:

Name	Type	Description
any		The metadata value, or defa if not found.

promise_all(*proms)

Wait for all promises to resolve.

Parameters:

Name	Type	Description	Default
*proms	Promise	Promises to combine.	()

Returns:

Name	Type	Description
PromiseAllAny		A promise that resolves when every input promise is done.

Example

await promise_all(delay_sim(seconds=5), my_task)

promise_any(*proms)

Wait for any one promise to resolve.

Parameters:

Name	Type	Description	Default
*proms	Promise	Promises to combine.	()

Returns:

Name	Type	Description
PromiseAllAny		A promise that resolves when the first input promise is done.

Example

await promise_any(delay_sim(seconds=5), abort_signal)

server_get_variable(key, defa=None)

Get a variable from the server task's scope.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
defa	optional	Default if variable is absent. Defaults to None.	None

Returns:

Name	Type	Description
any		Variable value, or defa.

server_set_variable(key, value=None)

Set a variable in the server task's scope.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
value	any	Value to assign. Defaults to None.	None

Returns:

Name	Type	Description
any		The value set, or value if no server task exists.

set_shared_variable(key, value)

Set a variable in the shared (Agent.SHARED) scope.

Shared variables are accessible from any task via get_shared_variable.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
value	any	Value to assign.	required

set_variable(key, value)

Set a variable in the current task's scope.

Parameters:

Name	Type	Description	Default
key	str	Variable name.	required
value	any	Value to assign.	required

sub_task_all(*args, **kwargs)

Schedule a task for each label and wait until all succeed (or any fails).

Like task_all but intended for use in sub-task contexts.

Parameters:

Name	Type	Description	Default
*args	label	Labels to schedule as tasks.	()
data	dict	Keyword argument passed as initial variables to every task. Defaults to None.	required

Returns:

Name	Type	Description
TaskPromiseAllAny	TaskPromiseAllAny	A promise that resolves when all tasks complete.

sub_task_schedule(label, data=None, var=None)

Schedule a sub-task under the current task starting at the given label.

Sub-tasks share lifecycle with the parent task.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to start the sub-task at.	required
data	dict	Initial sub-task variables. Defaults to None.	None
var	str	Variable name to store the created sub-task. Defaults to None.	None

Returns:

Name	Type	Description
MastAsyncTask	MastAsyncTask	The sub-task created, or None outside a task context.

task_all(*args, **kwargs)

Schedule a task for each label and wait until all tasks complete.

Parameters:

Name	Type	Description	Default
*args	label	Labels to schedule as parallel tasks.	()
data	dict	Keyword argument passed as initial variables to every task. Defaults to None.	required
sub_tasks	bool	Run as sub-tasks instead of top-level tasks. Defaults to False.	required

Returns:

Name	Type	Description
TaskPromiseAllAny	TaskPromiseAllAny	A promise that resolves when all tasks complete.

Example

await task_all(patrol_alpha, patrol_beta, patrol_gamma)

task_any(*args, **kwargs)

Schedule a task for each label and wait until any one task completes.

Parameters:

Name	Type	Description	Default
*args	label	Labels to schedule as parallel tasks.	()
data	dict	Keyword argument passed as initial variables to every task. Defaults to None.	required

Returns:

Name	Type	Description
TaskPromiseAllAny	TaskPromiseAllAny	A promise that resolves when the first task completes.

Example

await task_any(scan_target, timeout_label)

task_cancel(task)

Cancel and end the specified task immediately.

Parameters:

Name	Type	Description	Default
task	MastAsyncTask	The task to end.	required

task_schedule(label, data=None, var=None, defer=False, inherit=True, unscheduled=False)

Schedule a new task starting at the given label.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to start the task at.	required
data	dict	Initial task variables. Defaults to None.	None
var	str	Variable name to store the created task. Defaults to None.	None
defer	bool	Defer first tick to the next frame. Defaults to False.	False
inherit	bool	Inherit parent task variables. Defaults to True.	True
unscheduled	bool	Create without scheduling immediately. Defaults to False.	False

Returns:

Name	Type	Description
MastAsyncTask	MastAsyncTask	The task created, or None outside a task context.

task_schedule_client(label, data=None, var=None, defer=False, inherit=True, unscheduled=False)

Schedule a new task on the client starting at the given label.

Explicit client-side equivalent of task_schedule.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to start the task at.	required
data	dict	Initial task variables. Defaults to None.	None
var	str	Variable name to store the created task. Defaults to None.	None
defer	bool	Defer first tick to the next frame. Defaults to False.	False
inherit	bool	Inherit parent task variables. Defaults to True.	True
unscheduled	bool	Create without scheduling immediately. Defaults to False.	False

Returns:

Name	Type	Description
MastAsyncTask	MastAsyncTask	The task created, or None outside a client task context.

task_schedule_server(label, data=None, var=None, defer=False, inherit=True, unscheduled=False)

Schedule a new task on the server starting at the given label.

Like task_schedule but always runs under FrameContext.server_task.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to start the task at.	required
data	dict	Initial task variables. Defaults to None.	None
var	str	Variable name to store the created task. Defaults to None.	None
defer	bool	Defer first tick to the next frame. Defaults to False.	False
inherit	bool	Inherit parent task variables. Defaults to True.	True
unscheduled	bool	Create without scheduling immediately. Defaults to False.	False

Returns:

Name	Type	Description
MastAsyncTask	MastAsyncTask	The task created, or None outside a server task context.