5 Search Boundaries and Exceptions
This section specifies the dynamic boundary of a search: which code runs inside the search versus in host context, and how the observers (in-amb, in-amb/do) behave when an exception or reentrant read occurs.
5.1 Where Host Code Runs
The boundary of a search protects the body of the search and the continuations that it captures. An effect leaves its search before any code that interprets the choice runs, and only the continuation of the effect, when it is resumed, is inside a search again. So:
The body of a search, and every resumed continuation, run inside the search.
Eager pre-collection and shuffling (for/amb with #:length, its length expression and clauses/guards, and current-amb-shuffler) run at the choice point before make-amb leaves the search, under a supply mark (Code That Supplies Alternatives). They therefore see the search body’s dynamic parameters, while effects aimed at the enclosing search are rejected.
On-demand supply (the generator of make-amb, the sequence of sequence->amb, and for/amb clauses without #:length), and a choice’s merger from its first call on, run after leaving the search, in the dynamic extent of whoever calls them: first the caller of the search, later whoever asks for the next event. They follow the same rule, but need not see the same context. An effect in a merger belongs to the search around that caller, if there is one.
The handler of #:on-pause runs outside the search that it observes. An effect in it belongs to the search around the observer, if there is one.
Outside any search, an effect raises exn:fail:contract. With a supply mark active it reports the supply-phase error. Otherwise its message ends in not in a search.
5.2 After an Exception
When an exception escapes while reading from in-amb or in-amb/do, what happens next depends on where the exception was raised.
In the pause handler. The pause is over. The next read continues the search after that pause, and the handler is not called for it again. This holds for the stream of in-amb and for the sequence of in-amb/do alike; the stream has no element for that pause.
In the computation of the search, or when control leaves the computation through a continuation jump. The search cannot go on, since the part that has run cannot be run again. The next read, of the sequence or of the stream, raises exn:fail:contract with the message in-amb: the search cannot go on. The elements that a stream has already read stay in it.
> (define-values (more? get) (sequence-generate (in-amb/do (amb 1 (error "boom") 3)))) > (get) 1
> (get) boom
> (get) in-amb: the search cannot go on;
its last step has not returned: it is still running,
it raised an exception, or control escaped from it
A pause handler cannot read the element that it is producing. While the handler of a pause runs, reading that element, from the stream or from the sequence, raises exn:fail:contract with the message in-amb: an element cannot be read by the handler of its own pause, and nothing of the search runs. This error is an exception in the handler like any other: if the handler catches it and returns, the values that it returns are the element; if it escapes from the handler, the first case above applies. The handler may read the elements that the stream has read before.
The observers are not thread-safe, and their guarantees stop here:
If another thread reads an element while its pause handler is running, it gets the reentrancy error described above.
If the thread of a handler is killed while the handler runs, the cleanup on exit does not run. The element stays in the running state, and every later read raises the same reentrancy error.
Resuming the continuation of a handler several times must not be used to consume the single-pass state of a search more than once.