Promise functions

Awaitable promise helpers for coordinating parallel async operations.

Overview

Promises are objects returned by await-able functions. They represent a value that will be available in the future — when the associated task or condition completes. The promise functions module provides helpers for creating, combining, and querying promises in MAST.

promise_all resolves when every promise in a collection is done. promise_any resolves when the first promise completes. These are the lower-level primitives underlying task_all and task_any in the execution module — most scripts should use those instead.

promise_is_done and promise_result let you inspect a promise's state without blocking.

Quick example

MAST pyMAST

== run_parallel ==
    p1 = task_schedule(patrol_alpha)
    p2 = task_schedule(patrol_beta)
    await promise_all(p1, p2)
    log("Both patrols complete.")
    ->END

from sbs_utils.procedural.promise_functions import promise_all, promise_any, promise_is_done

p1 = task_schedule(patrol_alpha)
p2 = task_schedule(patrol_beta)

combined = promise_all(p1, p2)

if promise_is_done(combined):
    result = promise_result(combined)

API

`destroyed_all(the_set, snapshot=False)`

Build a promise that resolves when every object in a set is destroyed.

Parameters:

Name	Type	Description	Default
`the_set`	`Agent \| int \| set[Agent \| int]`	Object(s) to watch.	required
`snapshot`	`bool`	If True, take a copy of the set so later changes to the original do not affect what is watched. Defaults to False.	`False`

Returns:

Name	Type	Description
`TestPromise`		Resolves once no object in the set remains in the sim.

Example

await destroyed_all(enemies) "All enemies eliminated!"

`destroyed_any(the_set, snapshot=False)`

Build a promise that resolves when any object in a set is destroyed.

Parameters:

Name	Type	Description	Default
`the_set`	`Agent \| int \| set[Agent \| int]`	Object(s) to watch.	required
`snapshot`	`bool`	If True, take a copy of the set so later changes to the original do not affect what is watched. Defaults to False.	`False`

Returns:

Name	Type	Description
`TestPromise`		Resolves as soon as any object in the set no longer exists.

Example

await destroyed_any(enemies) "First kill achieved."

`distance_greater(obj_or_id1, obj_or_id2, distance)`

Build a promise that resolves when two objects are farther than a distance.

Parameters:

Name	Type	Description	Default
`obj_or_id1`	`Agent \| int`	First space object or ID.	required
`obj_or_id2`	`Agent \| int`	Second space object or ID.	required
`distance`	`float`	Threshold distance in simulation units.	required

Returns:

Name	Type	Description
`TestPromise`		Resolves when `dist(obj1, obj2) > distance`.

Example

await distance_greater(SHIP_ID, ENEMY_ID, 2000) "Enemy out of range."

`distance_less(obj_or_id1, obj_or_id2, distance)`

Build a promise that resolves when two objects are closer than a distance.

Parameters:

Name	Type	Description	Default
`obj_or_id1`	`Agent \| int`	First space object or ID.	required
`obj_or_id2`	`Agent \| int`	Second space object or ID.	required
`distance`	`float`	Threshold distance in simulation units.	required

Returns:

Name	Type	Description
`TestPromise`		Resolves when `dist(obj1, obj2) < distance`.

Example

await distance_less(SHIP_ID, ENEMY_ID, 500) "Enemy in range!"

`distance_point_greater(obj_or_id, point, distance)`

Build a promise that resolves when an object is farther than a distance from a point.

Parameters:

Name	Type	Description	Default
`obj_or_id`	`Agent \| int`	Space object or ID.	required
`point`	`Vec3`	Reference point in simulation space.	required
`distance`	`float`	Threshold distance in simulation units.	required

Returns:

Name	Type	Description
`TestPromise`		Resolves when `dist(obj, point) > distance`.

Example

await distance_point_greater(SHIP_ID, base_pos, 1000) "Ship has left the area."

`distance_point_less(obj_or_id, point, distance)`

Build a promise that resolves when an object is closer than a distance to a point.

Parameters:

Name	Type	Description	Default
`obj_or_id`	`Agent \| int`	Space object or ID.	required
`point`	`Vec3`	Reference point in simulation space.	required
`distance`	`float`	Threshold distance in simulation units.	required

Returns:

Name	Type	Description
`TestPromise`		Resolves when `dist(obj, point) < distance`.

Example

await distance_point_less(SHIP_ID, waypoint, 300) "Arrived at waypoint."

`grid_arrive_id(the_set, target_id, snapshot=False)`

Build a promise that resolves when grid objects arrive at a target cell.

Resolves the target cell position from target_id and delegates to grid_arrive_location.

Parameters:

Name	Type	Description	Default
`the_set`	`Agent \| int \| set[Agent \| int]`	Grid object(s) to watch.	required
`target_id`	`int`	ID of the grid object whose current position is used as the target cell.	required
`snapshot`	`bool`	If True, copy the set so later changes don't affect what is watched. Defaults to False.	`False`

Returns:

Name	Type	Description
`TestPromise`		Resolves when movement is complete, or a cancelled promise if `target_id` has no grid position.

`grid_arrive_location(the_set, x=0, y=0, snapshot=False)`

Build a promise that resolves when grid objects finish moving.

Checks whether the first object in the set no longer has the _moving_ role. The x and y parameters are accepted for API compatibility but are not used.

Parameters:

Name	Type	Description	Default
`the_set`	`Agent \| int \| set[Agent \| int]`	Grid object(s) to watch.	required
`x`	`int`	Unused target column. Defaults to 0.	`0`
`y`	`int`	Unused target row. Defaults to 0.	`0`
`snapshot`	`bool`	If True, copy the set so later changes don't affect what is watched. Defaults to False.	`False`

Returns:

Name	Type	Description
`TestPromise`		Resolves when the first object in the set is no longer moving.