Seals and restores for a :disk-snapshot KB that records its writes in an operation
log (vaelii.impl.oplog).
seal! writes the KB's derived state and starts the log again: the index image
(vaelii.impl.disk.index-snapshot), the belief image (vaelii.impl.belief-image), then
<dir>/oplog/seal.nippy, then a new generation of the log. It fsyncs the record store
before it writes seal.nippy, so every record below the watermark is on disk once a
seal names the watermark. seal.nippy holds the
generation, the records watermark — one above every handle the store held when the seal
was taken — and the two record fingerprints the images are stamped with. It is written
after both images and before the log restarts, so each crash point leaves a state an
open can tell apart:
seal.nippy: the images carry fingerprints the previous seal does not, so
neither installs against it, and the open rebuilds from the records;seal.nippy and before the restart: the log's header names the previous
generation, so its frames describe writes both images already hold, and the open
replays none of them.A KB is sealed when a :seal-class operation returns, when its directory closes, and
when its index drifts past vaelii.index.snapshot-drift: the drift is measured inside
a write, so the seal waits until the operation returns (oplog/request-seal!). A KB
belief-image/refusal names a reason for, or whose network does not cover its records,
cannot be sealed, and its log is marked unusable instead.
restore! takes a KB opened with {:recover? false} over the directory and brings it
to the state its last durable operation left. It installs both images against the
fingerprints seal.nippy records, attaches the log in replay mode, and replays the
current generation's frames (oplog/replay!). It declines — returning a reason and
leaving the caller to rebuild from the records — when there is no seal, the log is
unusable, an image does not install, a replayed write differs from the record stored at
its handle, or the store holds a record at or above the last handle the replay
allocated, which a write whose frame never reached the disk left behind.
A decline after the images installed leaves replayed state in the KB. restore! then
withdraws the directory's image writers and notes the :no-belief and :no-index
hazards (kb/note-hazards!), so closing that KB writes no image of the state.
Seals and restores for a `:disk-snapshot` KB that records its writes in an operation
log (`vaelii.impl.oplog`).
## A seal
`seal!` writes the KB's derived state and starts the log again: the index image
(`vaelii.impl.disk.index-snapshot`), the belief image (`vaelii.impl.belief-image`), then
`<dir>/oplog/seal.nippy`, then a new generation of the log. It fsyncs the record store
before it writes `seal.nippy`, so every record below the watermark is on disk once a
seal names the watermark. `seal.nippy` holds the
generation, the records watermark — one above every handle the store held when the seal
was taken — and the two record fingerprints the images are stamped with. It is written
after both images and before the log restarts, so each crash point leaves a state an
open can tell apart:
- before `seal.nippy`: the images carry fingerprints the previous seal does not, so
neither installs against it, and the open rebuilds from the records;
- after `seal.nippy` and before the restart: the log's header names the previous
generation, so its frames describe writes both images already hold, and the open
replays none of them.
A KB is sealed when a `:seal`-class operation returns, when its directory closes, and
when its index drifts past `vaelii.index.snapshot-drift`: the drift is measured inside
a write, so the seal waits until the operation returns (`oplog/request-seal!`). A KB
`belief-image/refusal` names a reason for, or whose network does not cover its records,
cannot be sealed, and its log is marked unusable instead.
## A restore
`restore!` takes a KB opened with `{:recover? false}` over the directory and brings it
to the state its last durable operation left. It installs both images against the
fingerprints `seal.nippy` records, attaches the log in replay mode, and replays the
current generation's frames (`oplog/replay!`). It declines — returning a reason and
leaving the caller to rebuild from the records — when there is no seal, the log is
unusable, an image does not install, a replayed write differs from the record stored at
its handle, or the store holds a record at or above the last handle the replay
allocated, which a write whose frame never reached the disk left behind.
A decline after the images installed leaves replayed state in the KB. `restore!` then
withdraws the directory's image writers and notes the `:no-belief` and `:no-index`
hazards (`kb/note-hazards!`), so closing that KB writes no image of the state.(attach! kb)kb — a :disk-snapshot KB whose belief and index cover its records — recording its
writes into a log under its directory, sealed once so the log starts at a generation
its images describe. Returns the logged KB.
`kb` — a `:disk-snapshot` KB whose belief and index cover its records — recording its writes into a log under its directory, sealed once so the log starts at a generation its images describe. Returns the logged KB.
seal.nippy's layout number. A seal of any other number is not restored.
`seal.nippy`'s layout number. A seal of any other number is not restored.
(read-seal dir)The seal dir holds, or nil.
The seal `dir` holds, or nil.
(restore! kb)Restore kb, opened {:recover? false} over its directory (the namespace docstring,
"A restore"). Returns {:restored true :kb lkb :frames n}, or {:restored false :reason r :clean? b}: :clean? false when the KB already holds replayed state and
the caller rebuilds by reopening rather than by recovering this value. A throw
declines as an unclean decline does — the log closed and the image writers withdrawn —
before it propagates.
Restore `kb`, opened `{:recover? false}` over its directory (the namespace docstring,
"A restore"). Returns `{:restored true :kb lkb :frames n}`, or `{:restored false
:reason r :clean? b}`: `:clean?` false when the KB already holds replayed state and
the caller rebuilds by reopening rather than by recovering this value. A throw
declines as an unclean decline does — the log closed and the image writers withdrawn —
before it propagates.(seal! kb)Seal kb (the namespace docstring, "A seal"). Returns {:sealed true :generation g}
or {:sealed false :reason r}.
Seal `kb` (the namespace docstring, "A seal"). Returns `{:sealed true :generation g}`
or `{:sealed false :reason r}`.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 |