116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# Spec 2 — Conditions and restarts, operational semantics
|
|
|
|
Status: **frozen** for the six hard cases below. Everything not listed here is
|
|
still open, but nothing in the implementation may depend on the unlisted parts.
|
|
|
|
Four operators: `handler-bind`, `handler-case`, `restart-case`, `invoke-restart`.
|
|
No condition class hierarchy — condition types are structs, matching is by type
|
|
plus an optional predicate.
|
|
|
|
## 1. `signal` returns `Unit`
|
|
|
|
`(signal c)` has type `Unit`, always. When every applicable handler returns
|
|
normally without transferring, `signal` returns `Unit` and the signalling
|
|
function simply carries on. This is the accumulation case.
|
|
|
|
The alternative — `signal` producing a value supplied by the handler — was
|
|
rejected: it forces every signal site to declare a default value and a result
|
|
type, which is a much heavier language for one convenience.
|
|
|
|
The consequence is visible in the syntax. A `restart-case` in value position
|
|
must produce its type on the *fall-through* path too:
|
|
|
|
```
|
|
(defn load-texture [path string] (Handle Texture)
|
|
(if (file-exists? path)
|
|
(rl/load-texture path)
|
|
(restart-case
|
|
(do (signal (AssetMissing {:path path}))
|
|
(abort "unhandled AssetMissing")) ; fall-through must not return
|
|
(use-placeholder [] placeholder-texture)
|
|
(retry [] (load-texture path)))))
|
|
```
|
|
|
|
`abort` has type `Never`, which unifies with anything. Any expression of type
|
|
`Never` (a `return`, a call to a diverging function) is equally acceptable there.
|
|
|
|
## 2. No handler
|
|
|
|
`signal` with no matching handler on the handler stack is a **no-op** that
|
|
returns `Unit`. It does not abort, does not print, does not enter a break loop.
|
|
`(error c)` is the diverging variant: same lookup, but with type `Never` and, if
|
|
nothing handles it, it enters the dev-build break loop or aborts in release.
|
|
|
|
The cost when unused is the intended one: `handler-bind` is a couple of stores
|
|
onto a stack-allocated linked-list frame, and `signal` with an empty stack is a
|
|
null check.
|
|
|
|
## 3. Restart signatures
|
|
|
|
```
|
|
(restart-case BODY
|
|
(name [p1 T1 p2 T2] BODY-1)
|
|
...)
|
|
```
|
|
|
|
- Parameters are annotated inline, like any other binding form.
|
|
- **Every clause body and the `restart-case` body must have the same type**, and
|
|
that is the type of the whole form.
|
|
- `(invoke-restart 'name arg ...)` has type `Never` — it never returns to the
|
|
invoking handler. Control resumes at the `restart-case`, which yields the
|
|
clause's value to *its* continuation.
|
|
- Argument count and types are checked at **runtime** in the first
|
|
implementation, because restarts are dynamically scoped and named. A statically
|
|
tracked restart set (Zig's error-set model) remains a nice-to-have.
|
|
|
|
## 4. Name shadowing
|
|
|
|
Restart lookup walks the dynamic restart stack from innermost outward and takes
|
|
the **first** frame offering the name. An inner `restart-case` therefore shadows
|
|
an outer one with the same name for the duration of its body. This is what makes
|
|
"restarts go at the resync point" composable: an inner parser's `skip-form` is
|
|
found before an outer one's.
|
|
|
|
`(find-restart 'name)` returns `(Option Restart)` so a handler can test before
|
|
committing; `(compute-restarts)` lists the visible frames for the debugger.
|
|
|
|
## 5. Cleanup during a transfer
|
|
|
|
Invoking a restart transfers control outward past zero or more frames.
|
|
|
|
- `defer` forms in every frame between the `invoke-restart` and the target
|
|
`restart-case` **do run**, innermost first, before the clause body starts.
|
|
- `errdefer` forms **do not run**. `errdefer` is bound to the `Result` failure
|
|
path (`try` returning `Err`) only. A restart transfer is not a failure — it is
|
|
a chosen recovery, and the recovery may well want the resource.
|
|
- The condition object lives on the *signalling* frame's stack. Nothing has
|
|
unwound when a handler runs, so it is valid there; but once a transfer starts,
|
|
the signalling frame dies. Anything a handler keeps must be copied out
|
|
(conditions are value structs, so `(push errors c)` copies).
|
|
|
|
## 6. Crossing compiler-generated frames
|
|
|
|
Transfer is lowered **explicitly** — result propagation plus branch targets — not
|
|
via platform unwinding, so that native and wasm32 behave identically. That means
|
|
every function on the path between the invoke and the target must be
|
|
transfer-aware: it returns a discriminated "normal value / transferring to frame
|
|
N" result, checks it after each call, and forwards.
|
|
|
|
- The compiler marks a function transfer-transparent if it can call, directly or
|
|
indirectly, anything that may invoke a restart. Escape analysis narrows this
|
|
set; functions outside it pay nothing.
|
|
- **Foreign frames cannot be crossed.** A restart transfer whose path passes
|
|
through a C frame (a raylib callback, an `extern` function calling back into
|
|
Flan) is a runtime error, not undefined behaviour. Handlers installed across an
|
|
FFI boundary must therefore either return normally or use `handler-case`
|
|
installed inside the callback.
|
|
- With the async state-machine transform, the handler and restart stacks live in
|
|
the **task** state, not thread-local, so a handler established before an
|
|
`await` is still in scope after resumption.
|
|
|
|
## What this does not settle
|
|
|
|
Condition inheritance/predicate-matching details, the break-loop UI, restart
|
|
interaction with threads, and whether `handler-case` should be a macro over
|
|
`handler-bind` + a transfer. None of these block milestone 5.
|