Skip to content

Wait for One or All

Make a task wait for the first of several things, or for all of them, and read which happened.


Before You Start


Steps

The Builder and YAML blocks in the steps are functions of one script, wait_for_one_or_all.py, in the order the blocks appear. Its start, which the functions share, is below. The line from desflow import Entity, SimulationContext follows it, and _shop is the first function of the first Builder block:

docs/snippets/guides/wait_for_one_or_all.py:header
import asyncio
import queue
import shutil
import tempfile
from pathlib import Path


class Capture:
    """An egress that keeps every event it receives."""

    def __init__(self):
        self.events = []

    async def run(self, egress_queue):
        try:
            while True:
                try:
                    batch = egress_queue.get_nowait()
                    self.events += [r for r in batch if r["stream_type"] == "event"]
                except queue.Empty:
                    await asyncio.sleep(0.005)
        except asyncio.CancelledError:
            pass


def _events(task: str, capture: Capture) -> list:
    return [e for e in capture.events if e["task"] == task]

The YAML blocks read their files from the folder of the script. Save each blueprint under the name in its title, wait_first.yaml, wait_tie.yaml, wait_all.yaml, wait_suspend.yaml, wait_each.yaml and wait_pool.yaml. The Low-level blocks are functions of a second script, wait_for_one_or_all_low_level.py, which Check the Result completes.

Wait for the First

wait: {any: {...}} ends when the first branch happens, as SimPy's AnyOf (a | b) does. Name each branch. After the wait, wait.<branch>.done says which happened. Here an order waits for a restock or 30 seconds. A builder function that declares wait reads the branches. A blueprint's payload reads wait.<branch>.done in a gen: expr field:

docs/snippets/yaml/wait_first.yaml:first
simulation: {sim_id: Shop, factor: 0}

signals: [restocked]

arrivals:
  orders:
    replay: {path: orders.csv}
    spawn: order
  restocks:
    replay: {path: restocks.csv}
    spawn: restock

tasks:
  order:
    wait:
      any:
        stock: {signal: restocked}
        limit: {timeout: 30}
    # wait.<branch>.done is true for each branch that was done when the wait ended
    payload:
      event_type: resumed
      done:
        stock: {gen: expr, expr: wait.stock.done}
        limit: {gen: expr, expr: wait.limit.done}
  restock:
    signal: restocked
    payload: {boxes: 6}

run: {until: 60}

first_yaml(gap) replays the order at 0 and the restock at gap from CSV files:

docs/snippets/guides/wait_for_one_or_all.py:yaml
def run_blueprint(blueprint: Path, arrivals: dict) -> Capture:
    """Runs a blueprint with its arrivals replayed from CSV files beside it.

    `arrivals` maps each file to its rows, such as {"orders.csv": "time\\n0\\n"}.
    """
    with tempfile.TemporaryDirectory() as tmp:
        folder = Path(tmp)
        shutil.copy(blueprint, folder)
        for file, rows in arrivals.items():
            (folder / file).write_text(rows)
        app = SimulationContext.from_yaml(folder / blueprint.name)
        capture = Capture()
        app.add_egress(capture)
        app.run()  # until the blueprint's run.until
    return capture


def first_yaml(gap: float, blueprint="wait_first.yaml") -> dict:
    capture = run_blueprint(
        Path(blueprint),
        {"orders.csv": "time\n0\n", "restocks.csv": f"time\n{gap}\n"},
    )
    return _events("order", capture)[-1]["value"]["done"]


def two_at_once_yaml(blueprint="wait_tie.yaml") -> dict:
    capture = run_blueprint(
        Path(blueprint),
        {
            "orders.csv": "time\n0\n",
            "boxes.csv": "time\n5\n",
            "labels.csv": "time\n5\n",
        },
    )
    return _events("order", capture)[-1]["value"]["done"]


def all_with_a_failure_yaml(blueprint="wait_all.yaml") -> list:
    capture = run_blueprint(
        Path(blueprint),
        {"orders.csv": "time\n0\n", "restocks.csv": "time,broken\n2,1\n"},
    )
    return [
        (e["sim_ts"], e["task"], e["value"].get("status", "finished"))
        for e in capture.events
        if e["task"] in ("order", "inspect") and e["value"].get("status") != "started"
    ]


def suspend_and_resume_yaml(blueprint="wait_suspend.yaml") -> list:
    capture = run_blueprint(Path(blueprint), {})
    return [
        (e["sim_ts"], e["value"]["by"])
        for e in _events("hold", capture)
        if e["value"].get("event_type") == "released"
    ]


def each_of_three_yaml(blueprint="wait_each.yaml") -> tuple:
    packed = _events("order", run_blueprint(Path(blueprint), {}))[-1]
    return packed["sim_ts"], packed["value"]["flags"]


def _pool_result(capture: Capture) -> tuple:
    """(time the order is packed, its granted flags, time the next order is packed),
    with None for a record that never comes."""
    packed = [e for e in _events("order", capture) if "granted" in e["value"]]
    late = [e for e in _events("late_order", capture) if "event_type" in e["value"]]
    return (
        packed[0]["sim_ts"],
        packed[0]["value"]["granted"],
        late[0]["sim_ts"] if late else None,
    )


def pool_of_requests_yaml(blueprint="wait_pool.yaml") -> tuple:
    return _pool_result(run_blueprint(Path(blueprint), {}))
docs/snippets/guides/wait_for_one_or_all.py:first
def _shop():
    app = SimulationContext("Shop", factor=0)
    capture = Capture()
    app.add_egress(capture)
    return app, capture


def first(gap: float) -> dict:
    """Which branches were done when the order's wait ended."""
    app, capture = _shop()
    app.add_signal("restocked")
    seen = {}

    @app.task(
        wait={"any": {"stock": {"signal": "restocked"}, "limit": {"timeout": 30}}}
    )
    def order(task_id, wait):
        # `wait` holds each branch's done, ok and value
        seen.update({name: branch["done"] for name, branch in wait.items()})
        return {"event_type": "resumed"}

    @app.task(signal="restocked")
    def restock(task_id):
        return {"boxes": 6}

    def script(context):
        context.spawn(order(0))
        yield context.env.timeout(gap)
        context.spawn(restock(0))

    app.add_process(script)
    app.run(until=60)
    return seen
docs/snippets/guides/wait_for_one_or_all_low_level.py:first
def first(gap: float) -> dict:
    """Which branches were done when the order's wait ended."""
    env = DynamicRealtimeEnvironment(factor=0)
    restocked = Signal(env, "restocked")
    seen = {}

    def order():
        branches = {"stock": restocked.wait(), "limit": env.timeout(30)}
        done = yield env.any_of(list(branches.values()))
        # The value of AnyOf holds the events that had happened
        seen.update({name: event in done for name, event in branches.items()})

    def restock():
        yield env.timeout(gap)
        restocked.fire({"boxes": 6})

    env.process(order())
    env.process(restock())
    env.run(until=60)
    env.teardown()
    return seen

With the restock at 10 seconds, every form returns {"stock": True, "limit": False}: the restock came first. With the restock at 50 seconds, it returns {"stock": False, "limit": True}. To route on the branch that happened, give the task a next with condition: wait.stock.done, as the example does.

When an any wait ends, its losing branches are cleaned up: a signal, timeout or condition branch is dropped, so it does nothing later. A losing child flow ({task: name}) keeps running to its end, as SimPy leaves a process running when nothing waits for it.

Read Both Branches When They Tie

Two branches can happen at the same simulation time. SimPy's AnyOf holds every event processed before the AnyOf itself, so both are in its value, and desflow reports both as done:

docs/snippets/yaml/wait_tie.yaml:tie
simulation: {sim_id: Shop, factor: 0}

signals: [boxes, labels]

arrivals:
  orders:
    replay: {path: orders.csv}
    spawn: order
  box_deliveries:
    replay: {path: boxes.csv}
    spawn: deliver_boxes
  label_deliveries:
    replay: {path: labels.csv}
    spawn: deliver_labels

tasks:
  order:
    wait:
      any:
        boxes: {signal: boxes}
        labels: {signal: labels}
    payload:
      event_type: resumed
      done:
        boxes: {gen: expr, expr: wait.boxes.done}
        labels: {gen: expr, expr: wait.labels.done}
  deliver_boxes:
    signal: boxes
    payload: {item: boxes}
  deliver_labels:
    signal: labels
    payload: {item: labels}

run: {until: 10}

two_at_once_yaml() runs it with run_blueprint, as first_yaml does.

docs/snippets/guides/wait_for_one_or_all.py:tie
def two_at_once() -> dict:
    """Two signals fire at the same instant: both branches are done."""
    app, capture = _shop()
    app.add_signal("boxes").add_signal("labels")
    seen = {}

    @app.task(
        wait={"any": {"boxes": {"signal": "boxes"}, "labels": {"signal": "labels"}}}
    )
    def order(task_id, wait):
        seen.update({name: branch["done"] for name, branch in wait.items()})
        return {"event_type": "resumed"}

    @app.task(signal="boxes")
    def deliver_boxes(task_id):
        return {"item": "boxes"}

    @app.task(signal="labels")
    def deliver_labels(task_id):
        return {"item": "labels"}

    def script(context):
        context.spawn(order(0))
        yield context.env.timeout(5)
        context.spawn(deliver_boxes(0))
        context.spawn(deliver_labels(0))

    app.add_process(script)
    app.run(until=10)
    return seen
docs/snippets/guides/wait_for_one_or_all_low_level.py:tie
def two_at_once() -> dict:
    """Two signals fire at the same instant: both branches are done."""
    env = DynamicRealtimeEnvironment(factor=0)
    boxes, labels = Signal(env, "boxes"), Signal(env, "labels")
    seen = {}

    def order():
        branches = {"boxes": boxes.wait(), "labels": labels.wait()}
        done = yield env.any_of(list(branches.values()))
        seen.update({name: event in done for name, event in branches.items()})

    def deliver():
        yield env.timeout(5)
        boxes.fire({"item": "boxes"})
        labels.fire({"item": "labels"})

    env.process(order())
    env.process(deliver())
    env.run(until=10)
    env.teardown()
    return seen

Every form returns {"boxes": True, "labels": True}. A model that routes on one branch should therefore check that branch, not assume that only one is done.

Wait for All

wait: {all: {...}} ends when every branch has happened, as SimPy's AllOf (a & b) does. If a branch fails first, the wait fails at once, with that branch's reason, and the task publishes failed. Branches still pending are cleaned up as for any, so a child flow runs on. Here the restock fails at 2 while the inspection, a child flow, runs until 4:

docs/snippets/yaml/wait_all.yaml:all
simulation: {sim_id: Shop, factor: 0}

signals: [restocked]

services:
  inspecting: {dist: constant, value: 4}

arrivals:
  orders:
    replay: {path: orders.csv}
    spawn: order
  restocks:
    replay: {path: restocks.csv}
    spawn: restock

tasks:
  order:
    wait:
      all:
        stock: {signal: restocked}
        check: {task: inspect}
    payload: {event_type: resumed}
  inspect:
    service: inspecting
    payload: {event_type: inspected}
  restock:
    signal: restocked
    fail: attr.broken == 1  # from the broken column of restocks.csv
    fail_reason: broken delivery
    payload: {boxes: 6}

run: {until: 10, on_unhandled_failure: continue}

all_with_a_failure_yaml() runs it with run_blueprint, with the restock at 2 marked broken in its CSV file.

docs/snippets/guides/wait_for_one_or_all.py:all
def all_with_a_failure() -> list:
    """(time, task, status) of the order and its inspection: the restock fails at 2,
    the order fails at once, and the inspection, still running, ends at 4."""
    app, capture = _shop()
    app.add_signal("restocked")
    app.add_service("inspecting", dist="constant", value=4)

    @app.task(
        wait={"all": {"stock": {"signal": "restocked"}, "check": {"task": "inspect"}}}
    )
    def order(task_id):
        return {"event_type": "resumed"}

    @app.task(service_id="inspecting")
    def inspect(task_id):
        return {"event_type": "inspected"}

    @app.task(
        signal="restocked", fail="attr.broken == 1", fail_reason="broken delivery"
    )
    def restock(task_id):
        return {"boxes": 6}

    def script(context):
        context.spawn(order(0))
        yield context.env.timeout(2)
        delivery = Entity("restocks-1", "restocks", {"broken": 1})
        context.spawn(restock(0, entity=delivery))

    app.add_process(script)
    app.run(until=10, on_unhandled_failure="continue")
    return [
        (e["sim_ts"], e["task"], e["value"].get("status", "finished"))
        for e in capture.events
        if e["task"] in ("order", "inspect") and e["value"].get("status") != "started"
    ]
docs/snippets/guides/wait_for_one_or_all_low_level.py:all
def all_with_a_failure() -> list:
    """(time, task, status) of the order and its inspection: the restock fails at 2,
    the order fails at once, and the inspection, still running, ends at 4."""
    env = DynamicRealtimeEnvironment(factor=0)
    restocked = Signal(env, "restocked")
    seen = []

    def inspect():
        yield env.timeout(4)
        seen.append((env.now, "inspect", "finished"))

    def order():
        seen.append((env.now, "order", "queued"))
        try:
            yield env.all_of([restocked.wait(), env.process(inspect())])
        except SignalFailed:
            # A failed branch fails the AllOf at once; the inspection runs on
            seen.append((env.now, "order", "failed"))

    def restock():
        yield env.timeout(2)
        restocked.fail("broken delivery")

    env.process(order())
    env.process(restock())
    env.run(until=10)
    env.teardown()
    return seen

Every form returns [(0.0, "order", "queued"), (2.0, "order", "failed"), (4.0, "inspect", "finished")]. The order's failure goes to its on_fail task when it has one, and otherwise ends its flow. on_fail needs no fail condition: a failed wait is enough to send the task there. A step or an expression of the task that cannot run, such as a service_time, a payload field or a gen: expr, fails the task in the same way. The task that on_fail names reads upstream.status, which is failed, and upstream.reason. In the low-level form, the failed signal raises SignalFailed in the order.

The restock's failure is one that no task handles, and a run stops at the first such failure unless run.on_unhandled_failure is continue. The blueprint sets run: {until: 10, on_unhandled_failure: continue}, and the Builder passes on_unhandled_failure="continue" to run. The low-level form needs no setting, because the order catches SignalFailed.

A wait for signals, tasks and times never holds a resource. Waiting for all of several things that each free up a resource does not grant the resources together: the task asks for its resource only after the wait, and another task can take the unit in between. To hold several resources at once, list them on the task, resource: [picker, bench], as Several Resources describes.

Nest Any and All

A branch of an any or an all may itself be an any or an all, so a wait nests to any depth. This wait is done when the invoice is printed and either two boxes are taken or 5 seconds pass:

docs/snippets/yaml/wait_groups.yaml:nested
1
2
3
4
5
6
7
8
9
# Go on once the invoice is printed and either two boxes are taken or 5 seconds pass
wait:
  all:
    invoice: {timeout: 4 s}
    either:
      any:
        boxes:
          get: {container: boxes, amount: 2}
        limit: {timeout: 5 s}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is yield (boxes | limit) & invoice.

Each branch name in the tree is unique. wait.<name> reads any node, whether a group or a leaf. For example, wait.either.done is true once the inner any is done, and wait.either.value maps its done leaves to their values.

Wait for Some of Them

wait: {at_least: 2, of: {a: ..., b: ..., c: ...}} is done when at least two of its branches are done. SimPy's Condition with a count rule does the same. at_least is a whole number of 1 or more, and an at_least above the number of branches is refused when the file loads. An empty of succeeds at once, whatever the count.

In a blueprint, an order waits for both its label and its invoice:

docs/snippets/yaml/wait_groups.yaml:all
1
2
3
4
5
# Go on once both the label and the invoice are printed
wait:
  all:
    label: {timeout: 2 s}
    invoice: {timeout: 4 s}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is yield env.all_of([label, invoice]), SimPy's AllOf.

It then waits for two of three checks:

docs/snippets/yaml/wait_groups.yaml:at-least
1
2
3
4
5
6
7
# Go on once two of the three checks have answered
wait:
  at_least: 2
  of:
    stock: {timeout: 1 s}
    payment: {timeout: 3 s}
    address: {timeout: 6 s}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is Condition(env, lambda events, count: count >= 2, [a, b, c]).

wait: {when: <expression>, of: {...}} is done when the expression holds. It is read each time a branch of of is processed, and once at the start for a branch that is processed already, as SimPy's Condition(env, evaluate, events) does. It reads wait.<branch>.done, .ok and .value of each branch, and done_count. A branch that fails fails the wait, and an empty of succeeds at once.

docs/snippets/yaml/wait_when.yaml:when
1
2
3
4
5
6
7
# Go on when the expression holds, read each time a branch is processed
wait:
  when: done_count >= 2 and wait.stock.done
  of:
    stock: {timeout: 1 s}
    payment: {timeout: 3 s}
    address: {timeout: 6 s}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is a Condition whose function reads the count and the events, as above.

The wait ends at 3 seconds, when the payment is the second branch done and the stock is one of them. The address check, which takes 6 seconds, is not done.

Wait for a Unit, an Item or Room

A branch may also be a resource request, a store or container get, or a put. A task can then wait for the first of a unit, an item, a signal or a time. A branch of each kind does this when it wins:

  • A request holds its unit through the task's service and gives it back when the task ends, as a listed resource does. Its wait.<branch>.value is the request.
  • A get takes an item, and wait.<branch>.value is that item.
  • A put adds the payload of the task before it, or None for the first task of a flow.

A single branch is named after its resource for a request, and get or put otherwise. An any ends when its first branch is granted. Only a branch processed before the wait ended is won. A request, get or put granted at the same instant, after the wait's condition was processed, is not won: the item of a get is lost, and the unit of a request stays with the task and goes back when the task ends. A request not yet granted is cancelled, so it holds nothing.

An interrupt with on_interrupt: restart during the wait starts the branches again. A request branch that holds its unit keeps it, and the other branches start again. A request branch that is still queued keeps its place in the line under resume and asks again at the back under restart. A unit granted at the instant of the interrupt stays held. An item a get already took is used by neither the old nor the new branch, because SimPy cannot put a taken item back.

This wait is for a packer or a time limit, and gives up the packer request if the limit comes first:

docs/snippets/yaml/wait_groups.yaml:request
1
2
3
4
5
6
7
# A packer asked for with priority 1 and without taking the unit from another order,
# or give up after 30 seconds; a packer won is held through packing
wait:
  any:
    unit:
      request: {resource: packers, priority: 1, preempt: false}
    limit: {timeout: 30 s}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is yield unit | env.timeout(30), as Add Reneging and Balking does.

A get branch with a time limit, whose value says why the wait ended:

docs/snippets/yaml/wait_groups.yaml:get
1
2
3
4
5
6
7
# Two boxes, or go on without them after 5 seconds with the value "no boxes"
wait:
  any:
    boxes:
      get: {container: boxes, amount: 2}
    limit:
      timeout: {after: 5 s, value: no boxes}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is yield boxes.get(2) | env.timeout(5).

A put branch on its own:

docs/snippets/yaml/wait_groups.yaml:put
1
2
3
# Put the closed order's payload on the shelf, waiting while the shelf is full
wait:
  put: {store: shelf}

@app.task(wait=...) takes the same mapping as a dict.

The low-level form is yield shelf.put(item).

Requests in a wait count in the order of acquisition: they come before the task's resource list. How a wait makes its requests depends on the group:

  • Under an all, or an at_least of 2 or more, the requests are made together. The first one granted is held while the others are waited for, so no other task can acquire two of them one after the other, in either order.
  • A single request branch of an any holds nothing while the any waits, and ends the any when it is granted. So such branches set no order.
  • A group branch of an any, such as an all of two requests, can hold a unit before the any is won. So its requests are made together with those of the other branches.

A model whose tasks acquire two resources in opposite orders loads and logs one WARNING, and a seize counts as holding. A task that keeps a resource for a next task that requests it in its wait is still refused when the model is built, because the request would wait behind the unit kept for it.

Park a Task Until Another Resumes It

wait: {suspend: true} parks the task until a resume of another task wakes it. The rules of resume and of an interrupt that reaches a parked task are in Park a Task Until Another Resumes It.

Here three orders park, at 1, 2 and 3 seconds, and a truck at 5 seconds wakes the two oldest:

docs/snippets/yaml/wait_suspend.yaml:suspend
simulation: {sim_id: Shop, factor: 0}

arrivals:
  orders: {dist: constant, value: 1, max_events: 3, spawn: hold}
  trucks: {dist: constant, value: 5, first_at: 5, max_events: 1, spawn: unload}

tasks:
  # Parks until a resume wakes it; wait.suspend.value is the value of that resume
  hold:
    wait: {suspend: true}
    payload:
      event_type: released
      by: {gen: expr, expr: wait.suspend.value}
  # Wakes the two oldest parked orders; the third stays parked
  unload:
    resume: {task: hold, limit: 2, value: truck-1}
    payload: {event_type: unloaded}

run: {until: 10}
docs/snippets/guides/wait_for_one_or_all.py:suspend
def suspend_and_resume() -> list:
    """(time, value) of each order a truck woke: it wakes the two oldest of three."""
    app, capture = _shop()
    woken = []

    @app.task(wait={"suspend": True})
    def hold(task_id, wait):
        # wait["suspend"]["value"] is the value of the resume that woke the order
        woken.append((float(app.env.now), wait["suspend"]["value"]))
        return {"event_type": "released"}

    @app.task(resume={"task": "hold", "limit": 2, "value": "truck-1"})
    def unload(task_id):
        return {"event_type": "unloaded"}

    def script(context):
        for number in range(3):
            yield context.env.timeout(1)
            context.spawn(hold(number))
        yield context.env.timeout(2)
        context.spawn(unload(0))

    app.add_process(script)
    app.run(until=10)
    return woken
docs/snippets/guides/wait_for_one_or_all_low_level.py:suspend
def suspend_and_resume() -> list:
    """(time, value) of each order a truck woke: it wakes the two oldest of three."""
    env = DynamicRealtimeEnvironment(factor=0)
    parked = []  # the event each parked order waits for, oldest first
    woken = []

    def hold():
        wake = env.event()
        parked.append(wake)
        value = yield wake  # the value of the succeed() that wakes it
        woken.append((env.now, value))

    def orders():
        for _ in range(3):
            yield env.timeout(1)
            env.process(hold())

    def truck():
        yield env.timeout(5)
        for wake in parked[:2]:  # the oldest first
            wake.succeed("truck-1")

    env.process(orders())
    env.process(truck())
    env.run(until=10)
    env.teardown()
    return woken

Every form wakes the first two orders at 5 seconds, with the value truck-1. The third stays parked until the run ends. The low-level form is SimPy's event.succeed(value) on the event that each process waits for.

Wait for a Computed Number of Branches

wait: {each: ..., group: ..., branch: ...} makes the same branch once for each element of each, when the wait starts. The rules of each, group and branch are in Wait for a Computed Number of Branches.

Here an order packs three boxes of 2, 5 and 9 seconds, and goes on when two are packed:

docs/snippets/yaml/wait_each.yaml:each
simulation: {sim_id: Shop, factor: 0}

arrivals:
  orders: {initial: 1, spawn: order}

tasks:
  order:
    wait:
      all:
        boxes:
          each: [2, 5, 9]  # one branch for each element
          group: {at_least: 2}  # done when two branches are
          branch:  # each.value is the element
            timeout: {after: each.value}
    payload:
      event_type: packed
      flags: {gen: expr, expr: wait.boxes.flags}  # which branches were done

run: {until: 30}
docs/snippets/guides/wait_for_one_or_all.py:each
def each_of_three() -> tuple:
    """(time, flags) of an order that packs three boxes, of 2, 5 and 9 seconds, and
    goes on when two are packed."""
    app, capture = _shop()
    seen = {}

    @app.task(
        wait={
            "all": {
                "boxes": {
                    "each": [2, 5, 9],
                    "group": {"at_least": 2},
                    "branch": {"timeout": {"after": "each.value"}},
                }
            }
        }
    )
    def order(task_id, wait):
        seen["done"] = (float(app.env.now), wait["boxes"]["flags"])
        return {"event_type": "packed"}

    def script(context):
        context.spawn(order(0))
        yield context.env.timeout(0)

    app.add_process(script)
    app.run(until=30)
    return seen["done"]
docs/snippets/guides/wait_for_one_or_all_low_level.py:each
from simpy.events import Condition


def each_of_three() -> tuple:
    """(time, flags) of an order that packs three boxes, of 2, 5 and 9 seconds, and
    goes on when two are packed."""
    env = DynamicRealtimeEnvironment(factor=0)
    seen = {}

    def order():
        boxes = [env.timeout(seconds) for seconds in (2, 5, 9)]
        done = yield Condition(env, lambda events, count: count >= 2, boxes)
        seen["done"] = (env.now, [box in done for box in boxes])

    env.process(order())
    env.run(until=30)
    env.teardown()
    return seen["done"]

Every form goes on at 5 seconds, and the flags are [True, True, False]. In SimPy, a Condition over the list of timeouts does the same: its count rule ends the wait at the second box.

open takes the same form, open: {pool: {each: ..., branch: ...}}, and starts the branches without waiting for them. A later wait: {handle: pool, index: 0}, cancel, release or interrupt names one element with {handle: pool, index: <expression>}, and cancel: pool cancels every element not yet granted. cancel works on requests, gets and puts, and interrupt on child flows. A handle leaf with an index waits for the element it first resolved, after a resume and after a restart. handle.pool.values and handle.pool.flags read the results. Here an order asks for three packers at once and packs with the first it is given. It cancels the two requests that were not granted and releases the first unit by name. A second order arrives at 1 second and asks for a packer:

docs/snippets/yaml/wait_pool.yaml:pool
simulation: {sim_id: Shop, factor: 0}

resources:
  packers: {current_cap: 1}

arrivals:
  orders: {initial: 1, spawn: order}
  late: {dist: constant, value: 1, first_at: 1, max_events: 1, spawn: late_order}

tasks:
  order:
    open:
      # three requests, made at once
      pool:
        each: 3
        branch: {request: packers}
    wait: {handle: pool, index: 0}  # the first of them
    service_time: 2
    cancel: pool  # the requests not yet granted: the second and the third
    release: {handle: pool, index: 0}  # the unit of the first, when the task ends
    payload:
      event_type: packed
      granted: {gen: expr, expr: handle.pool.flags}

  late_order:
    resource: packers
    service_time: 1
    payload: {event_type: late_packed}

run: {until: 30}
docs/snippets/guides/wait_for_one_or_all.py:pool
def pool_of_requests() -> tuple:
    """(time, granted, time of the next order) of an order that asks for three packers
    at once, packs with the first it gets and cancels the other two requests. A second
    order arrives at 1 s and asks for a packer."""
    from desflow.values import Template

    app, capture = _shop()
    app.add_resource("packers", current_cap=1)
    packed = Template(
        {
            "event_type": "packed",
            "granted": {"gen": "expr", "expr": "handle.pool.flags"},
        },
        name="tasks.order",
    )

    @app.task(
        open={"pool": {"each": 3, "branch": {"request": "packers"}}},
        wait={"handle": "pool", "index": 0},
        service_time=2,
        cancel="pool",  # the requests not yet granted: the second and the third
        release={"handle": "pool", "index": 0},
    )
    def order(task_id):
        return packed

    @app.task(resource_id="packers", service_time=1)
    def late_order(task_id):
        return {"event_type": "late_packed"}

    def script(context):
        context.spawn(order(0))
        yield context.env.timeout(1)
        context.spawn(late_order(0))

    app.add_process(script)
    app.run(until=30)
    return _pool_result(capture)
docs/snippets/guides/wait_for_one_or_all_low_level.py:pool
from simpy import Resource


def pool_of_requests() -> tuple:
    """(time, granted, time of the next order) of an order that asks for three packers
    at once, packs with the first it gets and cancels the other two requests. A second
    order arrives at 1 s and asks for a packer."""
    env = DynamicRealtimeEnvironment(factor=0)
    packers = Resource(env, capacity=1)
    seen: dict = {"late": None}

    def order():
        pool = [packers.request() for _ in range(3)]
        yield pool[0]
        yield env.timeout(2)  # the service
        for request in pool[1:]:
            request.cancel()  # a request not granted leaves the line
        packers.release(pool[0])
        seen["done"] = (env.now, [request.triggered for request in pool])

    def late_order():
        yield env.timeout(1)
        with packers.request() as request:
            yield request
            yield env.timeout(1)
        seen["late"] = env.now

    env.process(order())
    env.process(late_order())
    env.run(until=30)
    env.teardown()
    finished, granted = seen["done"]
    return finished, granted, seen["late"]

Every form returns the time the first order finishes, the flags of its three requests and the time the second order finishes: (2.0, [True, False, False], 3.0), with whole numbers in the Low-level form. Only the first request was granted. The cancel takes the other two out of the line, so the second order gets the unit at 2 seconds and finishes at 3. Without the cancel, the release would hand the unit to the second request, which nothing would ever release, and the second order would wait for ever. cancel: {handle: pool, index: 1} cancels one element, but it would leave the third request in the line, with the same result.

Wait for Nothing

An any or an all with no branches is accepted, and succeeds at once with an empty value. A task whose wait is {any: {}} or {all: {}} goes on in the step it starts, as SimPy's env.any_of([]) and env.all_of([]) do. With a patience of 0 the wait still wins. The empty wait succeeds the instant it is built, so it is already processed when the task resumes. The task therefore does not renege.


Check the Result

The script prints the result of every step above. The Builder and YAML functions end the script with:

docs/snippets/guides/wait_for_one_or_all.py:main
if __name__ == "__main__":
    print("check: restock after 10 s:", first(10))
    print("check: restock after 50 s:", first(50))
    print("check: two at once:", two_at_once())
    print("check: all, with a failure:", all_with_a_failure())
    print("check: the same in YAML:", first_yaml(10), first_yaml(50))
    print("check: two at once in YAML:", two_at_once_yaml())
    print("check: all, with a failure, in YAML:", all_with_a_failure_yaml())
    print("check: suspend and resume:", suspend_and_resume())
    print("check: suspend and resume, in YAML:", suspend_and_resume_yaml())
    print("check: two of three boxes:", each_of_three())
    print("check: two of three boxes, in YAML:", each_of_three_yaml())
    print("check: the first of three packers:", pool_of_requests())
    print("check: the first of three packers, in YAML:", pool_of_requests_yaml())

Run it in the folder with the script and the six blueprints, and keep the lines that start with check::

1
2
3
4
5
# With uv
uv run --no-project --with desflow wait_for_one_or_all.py | grep "^check:"
# With pip
pip install desflow
python wait_for_one_or_all.py | grep "^check:"
check: restock after 10 s: {'stock': True, 'limit': False}
check: restock after 50 s: {'stock': False, 'limit': True}
check: two at once: {'boxes': True, 'labels': True}
check: all, with a failure: [(0.0, 'order', 'queued'), (2.0, 'order', 'failed'), (4.0, 'inspect', 'finished')]
check: the same in YAML: {'stock': True, 'limit': False} {'stock': False, 'limit': True}
check: two at once in YAML: {'boxes': True, 'labels': True}
check: all, with a failure, in YAML: [(0.0, 'order', 'queued'), (2.0, 'order', 'failed'), (4.0, 'inspect', 'finished')]
check: suspend and resume: [(5.0, 'truck-1'), (5.0, 'truck-1')]
check: suspend and resume, in YAML: [(5.0, 'truck-1'), (5.0, 'truck-1')]
check: two of three boxes: (5.0, [True, True, False])
check: two of three boxes, in YAML: (5.0, [True, True, False])
check: the first of three packers: (2.0, [True, False, False], 3.0)
check: the first of three packers, in YAML: (2.0, [True, False, False], 3.0)

The Low-level script, wait_for_one_or_all_low_level.py, starts with the line from desflow import DynamicRealtimeEnvironment, Signal, SignalFailed, followed by the six Low-level functions in the order they appear above. It ends with:

docs/snippets/guides/wait_for_one_or_all_low_level.py:main
1
2
3
4
5
6
7
8
if __name__ == "__main__":
    print("restock after 10 s:", first(10))
    print("restock after 50 s:", first(50))
    print("two at once:", two_at_once())
    print("all, with a failure:", all_with_a_failure())
    print("suspend and resume:", suspend_and_resume())
    print("two of three boxes:", each_of_three())
    print("the first of three packers:", pool_of_requests())

It needs no blueprint. Run it:

1
2
3
4
5
# With uv
uv run --no-project --with desflow wait_for_one_or_all_low_level.py
# With pip
pip install desflow
python wait_for_one_or_all_low_level.py
1
2
3
4
5
6
7
restock after 10 s: {'stock': True, 'limit': False}
restock after 50 s: {'stock': False, 'limit': True}
two at once: {'boxes': True, 'labels': True}
all, with a failure: [(0, 'order', 'queued'), (2, 'order', 'failed'), (4, 'inspect', 'finished')]
suspend and resume: [(5, 'truck-1'), (5, 'truck-1')]
two of three boxes: (5, [True, True, False])
the first of three packers: (2, [True, False, False], 3)

The low-level form prints the times without a decimal point, because its timeouts are whole numbers.

The example is a shop where each order waits for a restock or 30 seconds, whichever comes first. A restock waits for both its delivery, which takes 10 seconds, and a stock count, which takes 20 seconds. Orders arrive about every 10 seconds, and a delivery every minute. The restocked signal fires once for each restock, so it is declared with once: false: a signal is one-shot by default, and a second firing stops the run. Its files are in Full Files. Save the form you use in a folder of its own, and run it:

The records go to the terminal as JSON lines. Keep the last count of each task and the time of each restock:

1
2
3
desflow run wait_for_one_or_all_example.yaml --stdout > records.jsonl
grep -oE '"path_id":"Shop.stats.tasks.(pack|refund).finished","value":[0-9]+' records.jsonl | tail -n 2
grep '"event_type":"restocked"' records.jsonl | grep -oE '"sim_ts":[0-9.]+'
"path_id":"Shop.stats.tasks.refund.finished","value":19
"path_id":"Shop.stats.tasks.pack.finished","value":22
"sim_ts":80.0
"sim_ts":140.0
"sim_ts":200.0
"sim_ts":260.0
"sim_ts":320.0
"sim_ts":380.0
"sim_ts":440.0
"sim_ts":500.0
"sim_ts":560.0
uv run --no-project --with desflow wait_for_one_or_all_example.py
{'pack': 22, 'refund': 19, 'restocked_at': [80.0, 140.0, 200.0, 260.0, 320.0, 380.0, 440.0, 500.0, 560.0]}
uv run --no-project --with desflow wait_for_one_or_all_example_low_level.py
{'pack': 22, 'refund': 19, 'restocked_at': [80, 140, 200, 260, 320, 380, 440, 500, 560]}

Each form runs once for 10 simulation minutes at factor=0: 22 orders are packed after a restock and 19 are refunded at the time limit. The restocks come at 80, 140 and so on to 560 seconds. Each comes 20 seconds after its delivery starts, because the wait for all ends with the stock count, the longer of its two branches. With any in place of all, each restock would come after the 10-second delivery instead, and more orders would be packed.

The process-interaction example waits for a child flow, then for the first of a courier's signal and a time limit. Processes shows how to download and run it.


Full Files

Full files
docs/snippets/yaml/wait_for_one_or_all_example.yaml
# The Wait for One or All guide: a shop where orders wait for a restock or a time
# limit, as wait_for_one_or_all_example.py builds it. Run it with:
# desflow run wait_for_one_or_all_example.yaml
simulation: {sim_id: Shop, factor: 0, random_seed: 42}

signals:
  restocked: {once: false}

arrivals:
  orders: {dist: exponential, rate: 0.1, spawn: order}
  deliveries: {dist: constant, value: 60, spawn: restock}

services:
  counting: {dist: constant, value: 20}

tasks:
  # Each order waits for the next restock or 30 seconds, whichever comes first
  order:
    wait:
      any:
        stock: {signal: restocked}
        limit: {timeout: 30}
    payload: {event_type: waited}
    next:
      when:
        - {condition: wait.stock.done, task: pack}
      default: refund
  pack:
    payload: {event_type: packed}
  refund:
    payload: {event_type: refunded}
  # A restock waits for its delivery, 10 seconds, and a stock count, a child flow
  # of 20 seconds; when both are done it finishes and fires restocked
  restock:
    wait:
      all:
        delivery: {timeout: 10}
        count: {task: count_stock}
    signal: restocked
    payload: {event_type: restocked}
  count_stock:
    service: counting
    payload: {event_type: counted}

stats: basic

run: {until: 10 min}
docs/snippets/guides/wait_for_one_or_all_example.py
"""Wait for one or all: a shop where orders wait for a restock or a time limit.

Each order waits for the next restock or 30 seconds, whichever comes first, and is
packed after a restock or refunded at the limit. A restock waits for both its
delivery and a stock count, then fires the signal the orders wait for. The script
runs 10 minutes at factor 0 and prints how many orders were packed and refunded, and
the times of the restocks: python wait_for_one_or_all_example.py.
"""

from desflow import SimulationContext

app = (
    SimulationContext(sim_id="Shop", factor=0, random_seed=42)
    .add_arrival("orders", dist="exponential", rate=0.1, spawn="order")
    .add_arrival("deliveries", dist="constant", value=60, spawn="restock")
    .add_service("counting", dist="constant", value=20)
    .add_signal("restocked", once=False)
    .with_stats("basic")
)


# Each order waits for the next restock or 30 seconds, whichever comes first
@app.task(
    wait={"any": {"stock": {"signal": "restocked"}, "limit": {"timeout": 30}}},
    next={
        "when": [{"condition": "wait.stock.done", "task": "pack"}],
        "default": "refund",
    },
)
def order(task_id):
    return {"event_type": "waited"}


@app.task()
def pack(task_id):
    return {"event_type": "packed"}


@app.task()
def refund(task_id):
    return {"event_type": "refunded"}


restocked_at = []  # the time of each restock


# A restock waits for its delivery, 10 seconds, and a stock count, a child flow of
# 20 seconds; when both are done it finishes and fires restocked
@app.task(
    wait={"all": {"delivery": {"timeout": 10}, "count": {"task": "count_stock"}}},
    signal="restocked",
)
def restock(task_id):
    restocked_at.append(app.env.now)
    return {"event_type": "restocked"}


@app.task(service_id="counting")
def count_stock(task_id):
    return {"event_type": "counted"}


def outcome() -> dict:
    """Runs 10 minutes and returns the orders packed and refunded, and the times of
    the restocks."""
    app.run(until="10 min")
    readings = app.env.stats.readings()
    counts = {
        task: readings[f"Shop.stats.tasks.{task}.finished"]
        for task in ("pack", "refund")
    }
    return {**counts, "restocked_at": restocked_at}


if __name__ == "__main__":
    print(outcome())
docs/snippets/guides/wait_for_one_or_all_example_low_level.py
"""Wait for one or all, low-level API: a shop where orders wait for a restock or a
time limit.

The low-level version of wait_for_one_or_all_example.py. Each order waits for the
next restock or 30 seconds, whichever comes first, and is packed after a restock or
refunded at the limit. A restock waits for both its delivery and a stock count, then
fires the signal the orders wait for. The script runs 10 minutes at factor 0 and
prints how many orders were packed and refunded, and the times of the restocks:
python wait_for_one_or_all_example_low_level.py.
"""

import itertools

from desflow import (
    DistributionConfig,
    DynamicRealtimeEnvironment,
    Sampler,
    SimParameter,
    Signal,
)

PARAMS = SimParameter(
    sim_id="Shop",
    arrival={"orders": DistributionConfig(dist="exponential", rate=0.1)},
)


def outcome() -> dict:
    """Runs 10 minutes and returns the orders packed and refunded, and the times of
    the restocks."""
    env = DynamicRealtimeEnvironment(factor=0)
    env.registry.register_sim_parameter(PARAMS)
    restocked = Signal(env, "restocked", once=False)
    counts = {"pack": 0, "refund": 0}
    restocked_at = []  # the time of each restock

    # Each order waits for the next restock or 30 seconds, whichever comes first
    def order():
        stock = restocked.wait()
        done = yield env.any_of([stock, env.timeout(30)])
        counts["pack" if stock in done else "refund"] += 1

    def count_stock():
        yield env.timeout(20)

    # A restock waits for its delivery, 10 seconds, and a stock count, a child
    # process of 20 seconds; when both are done it fires restocked
    def restock():
        yield env.all_of([env.timeout(10), env.process(count_stock())])
        restocked_at.append(env.now)
        restocked.fire()

    def orders(sampler):
        gap = env.registry.get_config("Shop.arrival.orders")
        while True:
            yield env.timeout(sampler.sample(gap))
            env.process(order())

    def deliveries():
        for _ in itertools.count():
            yield env.timeout(60)
            env.process(restock())

    env.process(orders(Sampler(seed=42)))
    env.process(deliveries())
    env.run(until=600)
    env.teardown()
    return {**counts, "restocked_at": restocked_at}


if __name__ == "__main__":
    print(outcome())