Commitf1d5b77eRecorded10 Jul 2026Repositorysigil-nrepl

Document interrupt/abort and output-streaming ops in README

Changed
 README.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)
Diff
README.mdmodified
@@ -30,8 +30,40 @@ Request format: `(request :id <string> :op <symbol> [:module <string>] [...param
30
31
Response format: `(response :id <string> :status <symbol> [...results])`
32
−33
Ops supported: `eval`, `complete`, `doc`, `describe`, `macroexpand`,
−34
`switch-module`, `modules`.
+33
Ops supported: `eval`, `abort` (alias `interrupt`), `complete`, `doc`,
+34
`describe`, `macroexpand`, `switch-module`, `modules`, plus the debug-protocol
+35
ops (`debug-policy`, `debug-state`, `debug-frames`, `debug-restarts`,
+36
`debug-quit`).
+37
+38
### Interrupt / abort
+39
+40
Expression evals run cooperatively — one preemptive-yield slice per
+41
`nrepl-process-pending` — so a CPU-bound eval (e.g. `(let loop () (loop))`) does
+42
not freeze the host's loop. Interrupt one from a second connection:
+43
+44
```
+45
(request :id <abort-id> :op abort :target-id <eval-request-id>)
+46
```
+47
+48
The abort responder gets `:status ok :aborted <eval-request-id>`; the
+49
interrupted eval receives `:status error :code "interrupted"`; the session
+50
survives and evaluates normally afterward. (A single top-level form that mixes
+51
a top-level `define` with a long loop runs on the immediate, non-abortable path
+52
— define at top level, then run, as separate requests.)
+53
+54
### Output streaming
+55
+56
Output written during an eval is streamed back incrementally as it happens,
+57
before the final response, carrying the original eval request id:
+58
+59
```
+60
(response :id <eval-id> :status out :out <string>) ; stdout
+61
(response :id <eval-id> :status err :err <string>) ; stderr
+62
```
+63
+64
followed by the normal terminal `(response :id <eval-id> :status ok :value …)`.
+65
The bundled `(sigil nrepl client)` transparently drains these frames and returns
+66
the terminal response from `nrepl-eval`.
67
68
## Embedding an nREPL server
69