What this process is holding beside the stores — one register every derived, droppable structure declares itself in, and one read over the lot.
The stores are measured elsewhere: catalog/heap reports the JVM's own figure and
catalog/footprint estimates what a loaded KB costs. Neither says anything about the
caches — the atoms and plain maps holding answers the engine would otherwise
recompute — and a hit rate is the only evidence a cost model has. "The
second query was fast" is a demo; "the second query was fast because it was served
from a cache, and here is the rate" is a measurement.
A register rather than a dozen accessors. This namespace requires only config, a
leaf that holds no cache, so the reader still has no require edge down to a namespace
holding one: every such namespace requires this one and declares itself at load, and
there is no list here that a new cache has to be added to twice. The config edge reads
one switch, VAELII_CACHE_SCALE, and limit-of applies it to every count-bounded
cache's limit. A cache in a namespace this
process never loaded — a qualitative calculus nobody registered, the metric-time
reasoner — is absent from the read because it is absent from the process, which is the
honest answer rather than a row of zeroes.
Two scopes, and never one wearing the other's clothes. :scope says what a row's
:entries counts: :kb for a cache hanging off a KB record, :process for a static
one every KB in the JVM shares. :counters says the same about :hits / :misses,
separately, because the literal cache is exactly the awkward case — its entries are
per-KB and its counters are global AtomicLongs, "since they measure the mechanism
rather than a store" (literal-cache/stats). Rendering that as one per-KB row would
attribute another KB's hits to this one. The closure neighbours are awkward the other
way round — process counters over entries only a live search step can count — which is
the same argument for keeping the two fields apart.
:unit is not decoration. One cache counts literals, another counts networks, a
third counts symbols, and a column of bare integers compares none of them.
A row whose :entries is nil is one that cannot be counted from outside — the
scope-bound caches, bound for the length of one chaining run or one search step and
garbage when it returns. They are registered all the same, with the reason in
:note, so the list is complete rather than merely finite.
A row answers for itself, and fails for itself. The register is open, so a read
here runs code this namespace has never seen; one that throws is reported as a row
carrying :error rather than allowed to take the answer down with it. A diagnostic
is worth most while something is already wrong, which is exactly when it must not be
the next thing to break.
What this process is holding beside the stores — one register every derived, droppable structure declares itself in, and one read over the lot. The stores are measured elsewhere: `catalog/heap` reports the JVM's own figure and `catalog/footprint` estimates what a loaded KB costs. Neither says anything about the **caches** — the atoms and plain maps holding answers the engine would otherwise recompute — and a hit rate is the only evidence a cost model has. "The second query was fast" is a demo; "the second query was fast because it was served from a cache, and here is the rate" is a measurement. **A register rather than a dozen accessors.** This namespace requires only `config`, a leaf that holds no cache, so the reader still has no require edge down to a namespace holding one: every such namespace requires *this* one and declares itself at load, and there is no list here that a new cache has to be added to twice. The `config` edge reads one switch, `VAELII_CACHE_SCALE`, and `limit-of` applies it to every count-bounded cache's limit. A cache in a namespace this process never loaded — a qualitative calculus nobody registered, the metric-time reasoner — is absent from the read because it is absent from the process, which is the honest answer rather than a row of zeroes. **Two scopes, and never one wearing the other's clothes.** `:scope` says what a row's `:entries` counts: `:kb` for a cache hanging off a KB record, `:process` for a static one every KB in the JVM shares. `:counters` says the same about `:hits` / `:misses`, separately, because the literal cache is exactly the awkward case — its entries are per-KB and its counters are global `AtomicLong`s, "since they measure the mechanism rather than a store" (`literal-cache/stats`). Rendering that as one per-KB row would attribute another KB's hits to this one. The closure neighbours are awkward the other way round — process counters over entries only a live search step can count — which is the same argument for keeping the two fields apart. **`:unit` is not decoration.** One cache counts literals, another counts networks, a third counts symbols, and a column of bare integers compares none of them. A row whose `:entries` is nil is one that cannot be counted from outside — the scope-bound caches, bound for the length of one chaining run or one search step and garbage when it returns. They are registered all the same, with the reason in `:note`, so the list is complete rather than merely finite. **A row answers for itself, and fails for itself.** The register is open, so a read here runs code this namespace has never seen; one that throws is reported as a row carrying `:error` rather than allowed to take the answer down with it. A diagnostic is worth most while something is already wrong, which is exactly when it must not be the next thing to break.
(assoc-bounded m limit k v)Store v at k in map m, clearing m wholesale when it already holds limit
entries.
The bound policy, in one place rather than spelled out at each cache. Wholesale
clearing rather than eviction is literal-cache/cache-limit's argument and
observe/resident-limit's before it: evicting exactly the right entry costs more
bookkeeping than the entry saved, and a cache that has grown past its bound is one
whose queries have moved on. That is a judgement about every cache here at once, so
it is worth being able to revisit in one edit rather than six.
Store `v` at `k` in map `m`, **clearing `m` wholesale** when it already holds `limit` entries. The bound policy, in one place rather than spelled out at each cache. Wholesale clearing rather than eviction is `literal-cache/cache-limit`'s argument and `observe/resident-limit`'s before it: evicting exactly the right entry costs more bookkeeping than the entry saved, and a cache that has grown past its bound is one whose queries have moved on. That is a judgement about every cache here at once, so it is worth being able to revisit in one edit rather than six.
(clear-caches kb)(clear-caches kb {:keys [counters?]})Drop every cache that offers a clear, and say what went: {:cleared [{:cache :label :entries} …] :entries total}, ranked like rows.
Not !, and the reason is the whole point of the control: every entry is derived, the
next read recomputes it, and no belief moves. That makes a clear a measuring
instrument rather than an edit — clear, ask the same question again, and watch the
miss the second ask no longer gets to skip.
Scoped to kb, because the argument says so. Every :clear drops that cache's
entries for this KB and nothing else. The hit and miss counters some caches keep are
process-wide — they measure the mechanism rather than a store — and zeroing one would
reset a rate every other KB in the JVM is reporting, mid-measurement. So it is not
done here: {:counters? true} asks for it, in a call that says out loud it is reaching
past its argument, and the answer then carries :counters-reset naming the caches it
touched. A function whose signature names one KB must not quietly be a per-process
control; caches' :counters column is how a caller knows which rows the option is
about.
A cache with no :clear is left alone and is not in the answer. Those are the
structural ones — the symbol pool, the compiled relation algebras — where dropping the
entries costs the sharing they exist for and buys no measurement.
A clear that throws costs its own entry and no other, the way a read does: its row
carries :error and an entry count of zero.
Drop every cache that offers a clear, and say what went: `{:cleared [{:cache :label
:entries} …] :entries total}`, ranked like `rows`.
Not `!`, and the reason is the whole point of the control: every entry is derived, the
next read recomputes it, and no belief moves. That makes a clear a measuring
instrument rather than an edit — clear, ask the same question again, and watch the
miss the second ask no longer gets to skip.
**Scoped to `kb`, because the argument says so.** Every `:clear` drops that cache's
entries *for this KB* and nothing else. The hit and miss counters some caches keep are
process-wide — they measure the mechanism rather than a store — and zeroing one would
reset a rate every other KB in the JVM is reporting, mid-measurement. So it is not
done here: `{:counters? true}` asks for it, in a call that says out loud it is reaching
past its argument, and the answer then carries `:counters-reset` naming the caches it
touched. A function whose signature names one KB must not quietly be a per-process
control; `caches`' `:counters` column is how a caller knows which rows the option is
about.
A cache with no `:clear` is left alone and is not in the answer. Those are the
structural ones — the symbol pool, the compiled relation algebras — where dropping the
entries costs the sharing they exist for and buys no measurement.
A clear that throws costs its own entry and no other, the way a read does: its row
carries `:error` and an entry count of zero.(grow!)Raise pressure one step back toward the operator's scale, and answer the new pressure. No trim: growing a bound drops nothing, it only lets the next store hold more.
Raise pressure one step back toward the operator's scale, and answer the new pressure. No trim: growing a bound drops nothing, it only lets the next store hold more.
(install-memory-guard! {:keys [kbs]})Attach a post-collection listener to the JVM's garbage collectors that moves the cache
profile's :pressure with how full the old generation is: over pressure-high it shrinks
the caches so the next collection reclaims, under pressure-low it grows them back.
:kbs is a thunk answering the live KB records whose per-KB caches the trim reaches — the
host supplies it from its catalog, since the engine holds no roster of open KBs.
Attached by the servers and by nothing at engine load, so a library embedding pays for no
listener it did not ask for. Idempotent: a second call replaces the :kbs thunk and arms
no second listener. A JVM whose collectors emit no such notification keeps pressure at 1.0
— the guard is a best-effort relief, not a guarantee. ! because it attaches to the
process's collectors; uninstall-memory-guard! detaches.
Attach a post-collection listener to the JVM's garbage collectors that moves the cache profile's `:pressure` with how full the old generation is: over `pressure-high` it shrinks the caches so the next collection reclaims, under `pressure-low` it grows them back. `:kbs` is a thunk answering the live KB records whose per-KB caches the trim reaches — the host supplies it from its catalog, since the engine holds no roster of open KBs. Attached by the servers and by nothing at engine load, so a library embedding pays for no listener it did not ask for. Idempotent: a second call replaces the `:kbs` thunk and arms no second listener. A JVM whose collectors emit no such notification keeps pressure at 1.0 — the guard is a best-effort relief, not a guarantee. `!` because it attaches to the process's collectors; `uninstall-memory-guard!` detaches.
(limit-of id default)The bound cache id enforces now, given its shipped default default. An override names
an absolute limit and replaces default: the operator's :scale leaves it alone, but the
guard's :pressure still multiplies it, so a filling heap shrinks a pinned cache like every
other. A default with no override is multiplied by both :scale and :pressure. Either
result is floored at min-limit. A nil default with no override — a cache bounded by
something other than a count — stays nil, since no multiplier acts on it.
Read on a cache's store path and by its rows entry, so the bound enforced and the bound
reported are one number. At scale 1.0 and pressure 1.0 with no override the shipped
default is returned as it stands.
The bound cache `id` enforces now, given its shipped default `default`. An override names an absolute limit and replaces `default`: the operator's `:scale` leaves it alone, but the guard's `:pressure` still multiplies it, so a filling heap shrinks a pinned cache like every other. A `default` with no override is multiplied by both `:scale` and `:pressure`. Either result is floored at `min-limit`. A nil `default` with no override — a cache bounded by something other than a count — stays nil, since no multiplier acts on it. Read on a cache's store path and by its `rows` entry, so the bound enforced and the bound reported are one number. At scale 1.0 and pressure 1.0 with no override the shipped `default` is returned as it stands.
(limit-thunk id default)#(limit-of id default), for a descriptor's :limit, so its rows entry reports the
effective bound rather than the shipped default. See register-cache.
`#(limit-of id default)`, for a descriptor's `:limit`, so its `rows` entry reports the effective bound rather than the shipped default. See `register-cache`.
(memory-guard)Whether the guard is attached to the collectors, and the pressure it currently holds:
{:installed? bool :pressure p}. Pressure below 1.0 says the guard has shrunk the caches
under a heap it is watching fill.
Whether the guard is attached to the collectors, and the pressure it currently holds:
`{:installed? bool :pressure p}`. Pressure below 1.0 says the guard has shrunk the caches
under a heap it is watching fill.(pressure-response frac pressure)What a post-collection old-generation frac (used over max) asks of the caches at the
current pressure: :shrink over pressure-high, :grow under pressure-low while
pressure is still below the operator's ceiling of 1.0, else :hold. A pure function of
the two readings, so the decision is tested without a heap that is actually full.
What a post-collection old-generation `frac` (used over max) asks of the caches at the current `pressure`: `:shrink` over `pressure-high`, `:grow` under `pressure-low` while pressure is still below the operator's ceiling of 1.0, else `:hold`. A pure function of the two readings, so the decision is tested without a heap that is actually full.
(profile)The cache profile in force: {:scale <operator multiplier> :pressure <guard multiplier> :overrides {cache-id limit}}. A cache's effective bound is its shipped default times
:scale times :pressure (an override replaces the default but the two multipliers still
apply, so the guard can shrink a pinned cache under memory pressure).
The cache profile in force: `{:scale <operator multiplier> :pressure <guard multiplier>
:overrides {cache-id limit}}`. A cache's effective bound is its shipped default times
`:scale` times `:pressure` (an override replaces the default but the two multipliers still
apply, so the guard can shrink a pinned cache under memory pressure).(read-through cache limit k compute)The value at k in the map held by atom cache, else (compute) — stored under
assoc-bounded's bound, and returned.
find rather than get, so a computed nil is a hit rather than a miss recomputed
forever. compute runs outside the swap! because it is the expensive half and a
swap! retry must not run it twice: two callers racing one key both compute and both
store, and the second store is a no-op — the trade a memo of derived values wants over
holding a lock across the computation.
The value at `k` in the map held by atom `cache`, else `(compute)` — stored under `assoc-bounded`'s bound, and returned. `find` rather than `get`, so a computed `nil` is a hit rather than a miss recomputed forever. `compute` runs outside the `swap!` because it is the expensive half and a `swap!` retry must not run it twice: two callers racing one key both compute and both store, and the second store is a no-op — the trade a memo of derived values wants over holding a lock across the computation.
(register-cache {:keys [cache] :as descriptor})Declare that this namespace holds a cache. Called at namespace load, once per cache.
Bare, not !: it installs a descriptor the next load replaces, the way set-solver
installs a setting.
The descriptor:
:cache a keyword naming it, unique across the process
:label what to call it on screen
:scope :kb or :process — what :entries counts
:unit what one entry is, since entries mix units across caches
:limit entries held before it is cleared wholesale, or nil for a cache
bounded by something other than a count (say what, in :note).
A thunk where the bound is a dynamic var or profile-scaled —
limit-thunk builds the profile-scaled one; see below
:counters :kb, :process, or nil when nothing counts hits and misses
:note one line: what it holds, and what retires an entry
:read (fn [kb]) -> {:entries n :hits h :misses m}, any key absent where
there is no number. O(1) — this runs on a page that polls.
A nil :entries says the cache cannot be counted from here.
:clear (fn [kb]) -> entries dropped, or absent when nothing drops it by hand.
Scoped to kb. A clear that reached past its argument would make
clear-caches a process-wide control wearing a per-KB signature
:trim (fn [kb target]) -> entries dropped, or absent. The partial drop the
memory-pressure guard uses: bring the cache down to target entries while
keeping the rest, where :clear drops everything. A :process cache
ignores kb; trim-map! is the plain-map one, the LRU trims by recency
:reset-counters (fn [kb]) -> the counters as they stood, or absent. Only a cache
whose :counters are :process has one, and it is separate from :clear
precisely because it is wider than kb
:read, :clear and :reset-counters all take the KB even when the cache is
process-wide, so a caller needs no second calling convention for the static ones; they
ignore it.
:limit takes a thunk for the same reason :read is a function. A descriptor is
built once, at namespace load, so a constant captured into it is that constant forever
— which is right for a def and wrong for a ^:dynamic var, since being rebindable is
the only reason such a var is dynamic. Reporting the root bound while the engine
enforces a bound somebody rebound would misreport the one field a reader uses to judge
whether a cache is about to flush. Write :limit (fn [] *the-var*) and the row reads
it where it is read.
Declare that this namespace holds a cache. Called at namespace load, once per cache.
Bare, not `!`: it installs a descriptor the next load replaces, the way `set-solver`
installs a setting.
The descriptor:
:cache a keyword naming it, unique across the process
:label what to call it on screen
:scope :kb or :process — what `:entries` counts
:unit what one entry *is*, since entries mix units across caches
:limit entries held before it is cleared wholesale, or nil for a cache
bounded by something other than a count (say what, in `:note`).
**A thunk where the bound is a dynamic var or profile-scaled** —
`limit-thunk` builds the profile-scaled one; see below
:counters :kb, :process, or nil when nothing counts hits and misses
:note one line: what it holds, and what retires an entry
:read (fn [kb]) -> {:entries n :hits h :misses m}, any key absent where
there is no number. **O(1)** — this runs on a page that polls.
A nil `:entries` says the cache cannot be counted from here.
:clear (fn [kb]) -> entries dropped, or absent when nothing drops it by hand.
**Scoped to `kb`.** A clear that reached past its argument would make
`clear-caches` a process-wide control wearing a per-KB signature
:trim (fn [kb target]) -> entries dropped, or absent. The **partial** drop the
memory-pressure guard uses: bring the cache down to `target` entries while
keeping the rest, where `:clear` drops everything. A `:process` cache
ignores `kb`; `trim-map!` is the plain-map one, the LRU trims by recency
:reset-counters (fn [kb]) -> the counters as they stood, or absent. Only a cache
whose `:counters` are `:process` has one, and it is separate from `:clear`
precisely because it is wider than `kb`
`:read`, `:clear` and `:reset-counters` all take the KB even when the cache is
process-wide, so a caller needs no second calling convention for the static ones; they
ignore it.
**`:limit` takes a thunk for the same reason `:read` is a function.** A descriptor is
built once, at namespace load, so a constant captured into it is that constant forever
— which is right for a `def` and wrong for a `^:dynamic` var, since being rebindable is
the only reason such a var is dynamic. Reporting the root bound while the engine
enforces a bound somebody rebound would misreport the one field a reader uses to judge
whether a cache is about to flush. Write `:limit (fn [] *the-var*)` and the row reads
it where it is read.(registered? id)Is id a cache registered in this process now? A membership test rather than a
refusal, because the register fills lazily: a cache is registered when its namespace
loads, and a qualitative calculus or the metric-time reasoner may not be loaded yet. So
set-limit reads this to warn on an id nothing has registered rather than to refuse
it — a not-yet-loaded cache would take the pin when it registers, where a refusal would
reject the very configuration a bulk load sets up before touching the calculus.
Is `id` a cache registered in *this* process now? A membership test rather than a refusal, because the register fills lazily: a cache is registered when its namespace loads, and a qualitative calculus or the metric-time reasoner may not be loaded yet. So `set-limit` reads this to *warn* on an id nothing has registered rather than to refuse it — a not-yet-loaded cache would take the pin when it registers, where a refusal would reject the very configuration a bulk load sets up before touching the calculus.
(reset-profile)Restore the configured profile — the VAELII_CACHE_SCALE scale, pressure 1.0 and no
overrides — and return it.
Restore the configured profile — the `VAELII_CACHE_SCALE` scale, pressure 1.0 and no overrides — and return it.
(rows kb)Every registered cache, read against kb, ranked by entries.
A row is the descriptor's static half — :cache :label :scope :unit :limit :counters :note — plus whatever its :read answered, plus :hit-rate and :clearable?. No
row walks the KB: each is a count off a map the engine is already holding, which is
what makes this pollable.
A row is data all the way down. The descriptor's three function slots — :read,
:clear, :reset-counters — are dropped, and what a caller needs of the last two is
the :clearable? flag and the :counters scope beside it. This is a public read
(vaelii.core/caches), served over RPC and rendered on a page, so a function left in a
row is a value neither can carry.
A read that throws costs its own row and no other, and the row carries :error
saying what went wrong. One broken descriptor taking the whole answer down would fail
the read exactly when the process is in the state it exists to describe.
Ranked by entries descending, ties broken on the cache's own name, so the order is a function of the content and two processes holding the same caches list them the same way. A row that cannot be counted sorts last, since a nil is not a small number.
Every registered cache, read against `kb`, ranked by entries. A row is the descriptor's static half — `:cache :label :scope :unit :limit :counters :note` — plus whatever its `:read` answered, plus `:hit-rate` and `:clearable?`. No row walks the KB: each is a count off a map the engine is already holding, which is what makes this pollable. **A row is data all the way down.** The descriptor's three function slots — `:read`, `:clear`, `:reset-counters` — are dropped, and what a caller needs of the last two is the `:clearable?` flag and the `:counters` scope beside it. This is a public read (`vaelii.core/caches`), served over RPC and rendered on a page, so a function left in a row is a value neither can carry. **A read that throws costs its own row and no other**, and the row carries `:error` saying what went wrong. One broken descriptor taking the whole answer down would fail the read exactly when the process is in the state it exists to describe. Ranked by entries **descending, ties broken on the cache's own name**, so the order is a function of the content and two processes holding the same caches list them the same way. A row that cannot be counted sorts last, since a nil is not a small number.
(set-limit id n)Pin cache id's bound to n regardless of scale, or clear the pin when n is nil, and
return the profile. A caller who names both a cache and a number has stated the bound it
wants, so the scale does not then move it.
Pin cache `id`'s bound to `n` regardless of scale, or clear the pin when `n` is nil, and return the profile. A caller who names both a cache and a number has stated the bound it wants, so the scale does not then move it.
(set-scale x)Multiply every count-bounded cache's shipped limit by x, and return the profile.
Reversible — 1.0 restores the shipped bounds — so bare, not !, as set-solver is:
it installs a setting the next cache store reads, and no belief moves.
Multiply every count-bounded cache's shipped limit by `x`, and return the profile. Reversible — `1.0` restores the shipped bounds — so bare, not `!`, as `set-solver` is: it installs a setting the next cache store reads, and no belief moves.
(shrink! kbs)Lower pressure one step and trim the caches to the new, lower bound; answer
{:pressure p :dropped n}. Public so the guard's response can be driven in a test without
a heap that is actually full.
Lower pressure one step and trim the caches to the new, lower bound; answer
`{:pressure p :dropped n}`. Public so the guard's response can be driven in a test without
a heap that is actually full.(trim-map! a target)Drop entries from the plain map held by atom a until it holds at most target, keeping
the target that iteration reaches first, and answer how many went. The kept set is
arbitrary rather than the most recent — a plain map records no recency — which is the trade
against a wholesale clear: half the entries survive a trim where none survive a clear, so
the reads they serve are not all recomputed at once. A cache whose entries carry recency
or a different shape supplies its own :trim rather than calling this.
Drop entries from the plain map held by atom `a` until it holds at most `target`, keeping the `target` that iteration reaches first, and answer how many went. The kept set is arbitrary rather than the most recent — a plain map records no recency — which is the trade against a wholesale clear: half the entries survive a trim where none survive a clear, so the reads they serve are not all recomputed at once. A cache whose entries carry recency or a different shape supplies its own `:trim` rather than calling this.
(uninstall-memory-guard!)Detach the guard's listener from every collector it armed and restore pressure to 1.0; answer the guard state. Safe when nothing is installed.
Detach the guard's listener from every collector it armed and restore pressure to 1.0; answer the guard state. Safe when nothing is installed.
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 |