Structured concurrency for bocpy: scoped `behaviors()` + `Terminator`

[matajoh]

Problem

bocpy today gives you @when(*cowns) and a single process-global rundown: wait() blocks until everything in the process has quiesced. That coarse rendezvous is fine for scripts and demos, but it has two sharp limits:

1. You can't wait for just your work. There's no way to say "block until this chunk of behaviors finishes" without also waiting for every unrelated behavior the same process happens to be running.
2. You can't wrap bocpy code in a synchronous API. Exposing behaviors and cowns to bocpy-aware consumers works beautifully. But if you want to hand a plain, synchronous function to a non-bocpy caller -- one that internally schedules behaviors and returns a finished result -- your only rendezvous is wait() / quiesce(), both of which drain the entire process, not just your call's work. So you can't cleanly build a blocking facade over bocpy internals.

We want structured concurrency: a first-class way to scope a unit of work, wait for exactly that work (including anything it transitively spawns), and get a result back -- without disturbing the rest of the process.

Proposed surface

A behaviors() scope

from bocpy import Cown, when, behaviors

c = Cown(0)

with behaviors() as scope:
    @when(c)
    def increment(c):
        c.value += 1

    @when(c)                # transitively belongs to `scope`
    def announce(c):
        print(f"c is {c.value}")

# The `with` block exits only once both behaviors have finished.
# Behaviors running elsewhere in the process keep going undisturbed.

Work scheduled from inside the scope -- even a deep chain of @when callbacks hopping across worker sub-interpreters -- belongs to the same scope, so the block correctly waits for all transitive work.

An explicit Terminator

The scope handle is a first-class object you can also build and pass by hand:

from bocpy import Terminator, when

t = Terminator()

@when(c, terminator=t)
def isolated(c):
    ...

assert t.wait(timeout=2.0)

A result value out of the scope

Pass the scope as one of a behavior's cowns and assign scope.value:

with behaviors() as scope:
    @when(a, b, scope)
    def summarise(a, b, scope):
        scope.value = a.value + b.value

print(scope.value)          # None if nothing wrote it

scope is acquired like any other cown, so the write is race-free and committed by the time the block exits. Single slot, last-writer-wins; the same discipline makes reductions (scope.value = (scope.value or 0) + k) safe.

Optional per-scope snapshots

with behaviors(stats=True, noticeboard=True) as scope:
    do_pipeline()

scope.stats        # scheduler-stats delta for just this scope's window
scope.noticeboard  # noticeboard snapshot taken at quiescence

What stays the same

• @when, Cown, whencall, send/receive, and the noticeboard keep their exact signatures and semantics.
• Omitting terminator= / not opening a scope -> today's process-global behavior.
• The public C ABI is untouched; downstream C extensions need no changes.

Guard rails (behavior changes to be aware of)

• Calling wait() / quiesce() inside a with behaviors(): block raises instead of silently deadlocking.
• A user Terminator that is still alive blocks the next runtime start().
• A behavior body declaring a parameter literally named terminator raises at decoration time (reserved name).

Feedback welcome

• Naming: behaviors() vs. something like scope() / nursery()? scope.value vs. scope.result?
• Should stats / noticeboard snapshots ship in the first cut, or land as a follow-up?
• Anything in the guard rails above that would surprise you in real code?

The design is written up in full in PLAN.md on the branch -- this issue is the short version to drive discussion while the work is in flight.

[mjp41]

It feels like we might want an entry in bocpy to access the global/toplevel scope. That would allow us to run some items internally that aren't required for termination of a sequential bit.

with behaviours():
  @when(a)
  def foo(a):
     ...
     @when(log, terminator=bocpy.global_scope)
     def write_log(log):
       ...

This way the logging can occur after the context manager has closed, but not before the BoC system has shutdown. This then allows the ordering of behaviour to be used to ensure log operations are correct internally, but not hold up the surrounding sequential code.

[mjp41]

Deadlock

BoC works very hard to prevent deadlock. This feature will break that, but I think it is acceptable
as we will be able to detect its occurance efficiently.

Example

So I have been thinking about potential deadlocks with this system. Here is an example that may
deadlock:

@when(a)
def foo(a):
  with behaviours() as scope:
     @when(b)
     def foo2:
        ...

@when(a,b)
def bar(a,b):
  ...

If bar is scheduled before foo2, then we get that

• bar is waiting for foo to finish,
• foo2 is waiting for b to become available, which is held by bar, and
• foo is waiting for next behaviours to terminate, which includes foo2.

This is a cycle that introduces deadlock.

Detecting deadlock

At the conclusion of a with behaviours() block, we wait on the terminator that was introduced by
the context. At this point, we can know the cowns held by all surrounding contexts. In the example above
that is just a. The behaviour graph reachable from those held cowns should not contain any behaviours from
the introduced scope.

In the example above, we get a DAG of the form

((a), global)
 -> ((a,b), global)
 -> ((b), scope)

Here we can easily see that a behaviour is in scope, and thus we are in a deadlock situation.
It is safe to walk this graph as we are preventing the release of (a) and thus transitively the behaviour on (a,b) can also not run.

From a practical point of view, we should only walk the graph after with has been waiting a certain length of time to prevent pointless work. While walking the graph we should keep checking the terminator for scope as we may be ready to go.

We might not know all the behaviours in a scope when we first start to wait. Consider the following slightly modified example:

@when(a)
def foo(a):
  with behaviours() as scope:
     @when()
     def foo3:
        @when(b)
        def foo2:
            ...

@when(a,b)
def bar(a,b):
  ...

Here we need foo3 to complete before we see the issue on foo2. This means we cannot just check once. To address this there seem to be many options to consider:

• Simply rechecking periodically,
• An epoch that is advanced when new behavious are generated in a scope,
• A visited set of cowns, that represents what is not allowed to be scheduled on in a context. Note this set can also grow after execution reaches the end of the context.
• Keeping an actively executing in scope count, and only searching for deadlock when that reaches zero, would be another sensible optimisation. Note that it can reach zero multiple times.

Walking the behaviour DAG is safe as nothing can be scheduled in this graph.

Read-only cowns

Care would be needed if this features is combined with read-only cown acquisition, in that case walking the graph is much more dangerous as behaviours can still be scheduled in the DAG of behaviours reachable from the held cowns. Probably would have to skip ahead to the next_writer. Read-only acquisition that is not active would need particular care.