Public entry point. Inert until init!.
Public entry point. Inert until `init!`.
Your toolkit in this running system — the namespace evaluated code
reaches for. It is aliased as __r in every namespace your evals
touch, so __r/… resolves wherever you navigate. The alias is for
eval code only; never write it into committed source.
Your toolkit in this running system — *the* namespace evaluated code reaches for. It is aliased as `__r` in every namespace your evals touch, so `__r/…` resolves wherever you navigate. The alias is for eval code only; never write it into committed source.
Evaluation: which namespace, and the eval itself.
The namespace a caller was last in is conversational state, so it lives with the caller's session (§11) rather than here.
Evaluation: which namespace, and the eval itself. The namespace a caller was last in is conversational state, so it lives with the caller's session (§11) rather than here.
Throwables as data, in two halves.
trace is the navigable half: a sequential, complete run of sites —
§3's second element type — so it reduces, filters and maps like any other
result in the library, and its elements feed nav/form:
(->> (exc/trace e) (filter :clj?) (map :sym) (map nav/form))
profile is the ocular half: what went wrong, pruned for reading, with a
trace attached. render turns a profile into a string. They are decoupled;
a profile is data, so the registry can store it and answer questions about
it later, which a string could not.
Throwables as data, in two halves.
`trace` is the navigable half: a sequential, complete run of **sites** —
§3's second element type — so it reduces, filters and maps like any other
result in the library, and its elements feed `nav/form`:
(->> (exc/trace e) (filter :clj?) (map :sym) (map nav/form))
`profile` is the ocular half: what went wrong, pruned for reading, with a
trace attached. `render` turns a profile into a string. They are decoupled;
a profile is data, so the registry can store it and answer questions about
it later, which a string could not.The Streamable HTTP transport, on the JDK's own HTTP server.
The MCP endpoint is /mcp, POST only. Quick protocol methods are answered
with plain JSON; a tools/call gets an SSE stream — opened immediately,
heartbeated with progress while the work runs, closed after its one
response message (§4). Nothing here initiates messages, so there is no GET
stream to offer and GET is 405 — news reaches the model by riding
responses instead (§5). Beside it, /probe is a sessionless GET answering
the server's identity for discovery and health checks (§11).
The Streamable HTTP transport, on the JDK's own HTTP server. The MCP endpoint is `/mcp`, POST only. Quick protocol methods are answered with plain JSON; a `tools/call` gets an SSE stream — opened immediately, heartbeated with progress while the work runs, closed after its one response message (§4). Nothing here initiates messages, so there is no GET stream to offer and GET is 405 — news reaches the model by riding responses instead (§5). Beside it, `/probe` is a sessionless GET answering the server's identity for discovery and health checks (§11).
JSON-RPC dispatch for MCP.
Takes a parsed request map, returns a response map. No I/O and no transport concerns — which is what makes it testable without a socket.
JSON-RPC dispatch for MCP. Takes a parsed request map, returns a response map. No I/O and no transport concerns — which is what makes it testable without a socket.
A namespace at a glance, from the running system's own metadata: every
var with its signature, source order preserved, privates included and
marked — the gist of a namespace, not just its API (§7). Runtime over
parsing, deliberately: everything the glance needs — arglists, doc,
the macro and private flags, line — already sits on the vars, for any
loaded namespace with no file plumbing, and reflects what is live after
a hot reload rather than what is on disk. Source-level outlining
(unloaded files, comment blocks, the shape of a file as written) is
form/changed-forms territory and stays there.
A namespace at a glance, from the running system's own metadata: every var with its signature, source order preserved, privates included and marked — the gist of a namespace, not just its API (§7). Runtime over parsing, deliberately: everything the glance needs — arglists, doc, the macro and private flags, line — already sits on the vars, for any loaded namespace with no file plumbing, and reflects what is live after a hot reload rather than what is on disk. Source-level outlining (unloaded files, comment blocks, the shape of a file as written) is `form`/`changed-forms` territory and stays there.
Recipes: each namespace below demonstrates one shape of async eval
against this system, as real code — loaded with the library, so a
recipe that stops compiling breaks the load rather than quietly
rotting. (__r/nses "patterns") is the index; outline a recipe
namespace for its signatures and docstrings; file it for the
(comment …) walkthroughs, which is where eval-by-eval choreography
lives. Walkthrough code is eval code: it assumes the scratch
refers (qlet, qfor, …) and the __r/__q aliases, like any
eval. These namespaces speak the tooling spelling throughout — __q,
the alias your evals carry everywhere — not the q of committed user
code, which is yours to require in source you own. House discipline:
defns and comment blocks only, nothing effectful at the top level —
these namespaces load inside the host JVM at boot, so loading must be
inert.
Recipes: each namespace below demonstrates one shape of async eval against this system, as real code — loaded with the library, so a recipe that stops compiling breaks the load rather than quietly rotting. `(__r/nses "patterns")` is the index; `outline` a recipe namespace for its signatures and docstrings; `file` it for the `(comment …)` walkthroughs, which is where eval-by-eval choreography lives. Walkthrough code is *eval* code: it assumes the scratch refers (`qlet`, `qfor`, …) and the `__r`/`__q` aliases, like any eval. These namespaces speak the tooling spelling throughout — `__q`, the alias your evals carry everywhere — not the `q` of committed user code, which is yours to require in source you own. House discipline: defns and comment blocks only, nothing effectful at the top level — these namespaces load inside the host JVM at boot, so loading must be inert.
No vars found in this namespace.
Deadlines. Two different waits are boundable, and they are not the
same: the eval's await bounds how long the response waits before
returning running — the work continues regardless, addressed by its
id — where __q/timeout bounds the work itself. Reach for await
when you only want your answer sooner; reach for timeout when work
still running past the deadline should die.
Deadlines. Two different waits are boundable, and they are not the same: the eval's `await` bounds how long the *response* waits before returning `running` — the work continues regardless, addressed by its id — where `__q/timeout` bounds the *work* itself. Reach for `await` when you only want your answer sooner; reach for `timeout` when work still running past the deadline should die.
Stateful cleanup around async work: open, lend, release — however the
work settles. __q/finally is the handler for it, because it is the
only one that also runs on cancellation: an eval can be cancelled by
id at any moment, and a resource opened inside one must not leak when
it is.
Stateful cleanup around async work: open, lend, release — however the work settles. `__q/finally` is the handler for it, because it is the only one that also runs on cancellation: an eval can be cancelled by id at any moment, and a resource opened inside one must not leak when it is.
Other async currencies, spent here directly. A CompletableFuture —
and anything else Quiescent recognizes: Future, another task —
returned from eval code is grounded like a task: the eval awaits it,
and its value is what the entry captures, with no adapter code.
core.async is the one explicit conversion, and only available when
the host system carries core.async.
Other async currencies, spent here directly. A `CompletableFuture` — and anything else Quiescent recognizes: `Future`, another task — returned from eval code is grounded like a task: the eval awaits it, and its value is what the entry captures, with no adapter code. core.async is the one explicit conversion, and only available when the host system carries core.async.
Repeating async work has two honest shapes, and one trap between
them. Parallel: qfor, one task per element. Sequential: plain
imperative code inside a single task — these are virtual threads,
so blocking is cheap and Thread/sleep in a loop is simply correct.
The trap is mixing the two: dotimes/doseq/run! spawning tasks
makes orphans — children never returned, cascade-cancelled the moment
the form settles, silently. __q/sleep itself is fine composed —
(qdo (__q/sleep 1000) (fire!)) is delay-then-do — the trap is
discarding what it returns. If you reached for dotimes around
__q/task or __q/sleep, reach for one of the shapes below instead.
Repeating async work has two honest shapes, and one trap between them. Parallel: `qfor`, one task per element. Sequential: plain imperative code *inside a single task* — these are virtual threads, so blocking is cheap and `Thread/sleep` in a loop is simply correct. The trap is mixing the two: `dotimes`/`doseq`/`run!` spawning tasks makes orphans — children never returned, cascade-cancelled the moment the form settles, silently. `__q/sleep` itself is fine *composed* — `(qdo (__q/sleep 1000) (fire!))` is delay-then-do — the trap is discarding what it returns. If you reached for `dotimes` around `__q/task` or `__q/sleep`, reach for one of the shapes below instead.
Work that must survive the eval that started it. An eval grounds each
top-level form, and tasks spawned but not returned are children —
cancelled, silently, when their form settles. Two honest ways out:
prefer letting the eval itself be the long-running work, addressed
by its id; reach for __q/compel when the work genuinely must detach.
Work that must survive the eval that started it. An eval grounds each top-level form, and tasks spawned but not returned are children — cancelled, silently, when their form settles. Two honest ways out: prefer letting the eval itself *be* the long-running work, addressed by its id; reach for `__q/compel` when the work genuinely must detach.
Fanning out inside a system that is also doing its day job. Tasks in
data structures already run in parallel — (__q/task {:a (f) :b (g)})
grounds both at once — and qfor maps in parallel when its body
spawns tasks. The recipe worth naming is the brake: a gate bounds
how many run at once, because an unbounded fan-out over production
data competes with production.
Fanning out inside a system that is also doing its day job. Tasks in
data structures already run in parallel — `(__q/task {:a (f) :b (g)})`
grounds both at once — and `qfor` maps in parallel when its body
spawns tasks. The recipe worth naming is the brake: a `gate` bounds
how many run at once, because an unbounded fan-out over production
data competes with production.Seeing into work that has not settled. Two channels exist, and they
compose: printed output streams — a running eval's latest printed
line is its live progress message, and everything printed so far is
readable mid-run with (__r/out id) — and shared state waits, an
atom the work fills and a later eval reads at its own rhythm.
Seeing into work that has not settled. Two channels exist, and they compose: printed output streams — a running eval's latest printed line is its live progress message, and everything printed so far is readable mid-run with `(__r/out id)` — and shared state waits, an atom the work fills and a later eval reads at its own rhythm.
The rolling registry: every eval, captured (§5).
An entry is a q/task, not a value — what is retained is something that
will eventually complete, which is what makes an id useful before the work
is finished and a valid input to q/catch, q/finally and q/cancel
after it.
State lives here behind defonce and nothing else lives here at all: the
library namespaces above churn constantly during development, and ids that
evaporate on reload would break the property the registry exists for —
that an id keeps resolving.
The rolling registry: every eval, captured (§5). An entry is a `q/task`, not a value — what is retained is something that will eventually complete, which is what makes an id useful before the work is finished and a valid input to `q/catch`, `q/finally` and `q/cancel` after it. State lives here behind `defonce` and nothing else lives here at all: the library namespaces above churn constantly during development, and ids that evaporate on reload would break the property the registry exists for — that an id keeps resolving.
Session state: who is connected, when they last spoke, and the conversational state that belongs to one dialogue rather than to the JVM — the sticky namespace, the told-once ledger's audience, the tool-list fetch marker, queued eviction news (§11).
Streamable HTTP sessions are server-minted: initialize gets an id in
the Mcp-Session-Id response header and the client echoes it on every
subsequent request (measured 2026-08-04, claude-code 2.1.220). Sessions
are cheap and ephemeral — a reconnect abandons the old one without the
spec's DELETE goodbye (measured the same day) — so everything here
expires by silence, and an id never seen before is adopted rather than
404'd: after a server restart the client keeps presenting its old id,
and forcing a re-initialize would buy spec strictness at the price of
churn. A deliberate deviation, recorded in §11.
State lives behind defonce for the same reason the registry's does:
library reloads must not end anyone's session.
Session state: who is connected, when they last spoke, and the conversational state that belongs to one dialogue rather than to the JVM — the sticky namespace, the told-once ledger's audience, the tool-list fetch marker, queued eviction news (§11). Streamable HTTP sessions are server-minted: `initialize` gets an id in the `Mcp-Session-Id` response header and the client echoes it on every subsequent request (measured 2026-08-04, claude-code 2.1.220). Sessions are cheap and ephemeral — a reconnect abandons the old one without the spec's DELETE goodbye (measured the same day) — so everything here expires by silence, and an id never seen before is adopted rather than 404'd: after a server restart the client keeps presenting its old id, and forcing a re-initialize would buy spec strictness at the price of churn. A deliberate deviation, recorded in §11. State lives behind `defonce` for the same reason the registry's does: library reloads must not end anyone's session.
Output capture: the root *out* and *err* tees and the per-eval banks
they fill.
A tee sits at the one point every unbound deref of its var arrives at —
the var's root — and discriminates per write, not per install: every
write passes through to the original writer unchanged, and writes whose
thread carries a bank in scope are additionally copied into that bank.
It never diverts, never withholds, never attributes by wall-clock
coincidence (§11). Host threads that bound *out* or *err* themselves
never reach the root and never see the tee.
Both streams fill the same bank, interleaved in arrival order and
unmarked — chronology beats channel separation, as in a terminal — so
what *err* carries reaches the reader at last: warnings (a refer
rejected in favor of an interned def says so only here — measured
2026-08-05, invisible then), reflection notes, stack traces from
stray threads, anything host code mutters.
Output capture: the root `*out*` and `*err*` tees and the per-eval banks they fill. A tee sits at the one point every unbound deref of its var arrives at — the var's root — and discriminates per write, not per install: every write passes through to the original writer unchanged, and writes whose thread carries a bank in scope are additionally copied into that bank. It never diverts, never withholds, never attributes by wall-clock coincidence (§11). Host threads that bound `*out*` or `*err*` themselves never reach the root and never see the tee. Both streams fill the *same* bank, interleaved in arrival order and unmarked — chronology beats channel separation, as in a terminal — so what `*err*` carries reaches the reader at last: warnings (a refer rejected in favor of an interned def says so only here — measured 2026-08-05, invisible then), reflection notes, stack traces from stray threads, anything host code mutters.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |