tur/trail

nil (never performed; used only as a #fx{Bt} row annotation)

(defn bind-var [c : BtCell v : int] #fx{Bt} : bool (bt-set! c v))

A BtCell. Release with bt-cell-free.

(bt-get (bt-cell-new 0))  ; => 0

A BtCell in the unbound state.

(bt-bound? (bt-lvar-new 0))  ; => false

(bt-cell-free c)

Its current value.

(bt-get c)  ; => 0

true once bound. Always true for a value cell.

(bt-bound? v)  ; => false

true on success; false when `c` is a write-once cell that is already bound -- binding twice is a caller bug, not a silent overwrite.

(bt-set! c 42)  ; => true

A GCell. Release with g-cell-free.

(g-get (g-cell-new 7))  ; => 7

(g-cell-free g)

Its current value.

(g-get g)  ; => 7

(g-set! g 7)

A Mark. Pass it to bt-undo-to! to restore, or bt-commit-to! to keep.

(let [m (bt-mark)] (bt-set! c 1) (bt-undo-to! m))

true on success; false when `m` is STALE -- already undone, already committed, or from a level index that has since been reused. A stale undo is refused rather than performed: it is what a re-entered continuation produces, and quietly "succeeding" would restore words belonging to some other level's cells.

(bt-undo-to! m)  ; => true

true on success; false when `m` is stale.

(bt-commit-to! m)  ; => true

The level depth.

(bt-level)  ; => 0

The entry count.

(bt-depth)  ; => 1

(untrailed-begin) (bt-set! counter 1) (untrailed-end)

(untrailed-end)

Whatever `body` returned. The VALUE survives; the trailed WRITES do not. Returning something that points into state the scope just undid is the caller's problem -- this is a search primitive, not a memory-safe region.

(bt-scope (fn [] (do (bt-set! c 99) (bt-get c))))  ; => 99, c restored

TWO THINGS THAT COMPOSE SURPRISINGLY:

  1. `bt-commit-to!` inside the body escapes this scope ENTIRELY, not just
     one level. Commit means "promote to level 0" -- it discards the undo
     information rather than merging it into the enclosing level -- so a
     committed write survives every enclosing `bt-scope` too. That is
     deliberate (it is how a learned clause outlives a backjump), but it is
     the opposite of what "commit into the parent" suggests to a Prolog ear.

  2. A panic inside `body` skips the undo, leaving the trail at the inner
     level. A later `bt-undo-to!` on an OUTER mark still unwinds past it,
     but anything reading cells in between sees the body's writes. There is
     no unwind protection to hang the restore on.

The `bt-undo-to!` result is discarded: it reports only that the mark was
already spent, which inside this bracket means the body undid or committed
its own enclosing level -- covered by note 1.

Carries `#fx{Bt}` itself (it pushes and unwinds a level); `body` is
deliberately left without a declared row, so a body that also prints or
performs its own effects is not rejected at the bracket.

Whatever `body` returned.

(let [m (bt-mark)]
    (with-untrailed (fn [] (bt-set! c 7)))
    (bt-undo-to! m)
    (bt-get c))                                      ; => 7, not restored

Same panic caveat as `bt-scope`, and worse: a panic inside `body` leaves
trailing paused for everything after it, so later writes silently stop
being undoable. Do not put fallible work here that a `bt-scope` could hold.

(trail-reset!)