Joseph Ferano
57fe91f303
FIX.org, NEXT.md, DISCUSS.org, docs/DISCUSS.md and the session handoff at the root are one TODO.org now: 293 entries under seven subsystem headings, each carrying an org keyword that says where it stands. A DONE entry is a few lines saying what was decided and what that rules out; the reasoning that would not compress — the embedding spike and the four reports the hand-written x86 backend was built from — moved into docs/BUILT.md instead, and its entries point there in one line. Every entry was checked against the tree before it got a keyword, and the prose was wrong in both directions. Things the deleted files called open were built: the first-evaluation stall, main being redefinable, macro parameter lists, the type-limit constants, the array constructors, the byte fills, inc/dec, the discard's fontification, the Emacs buffers, rt_die's _exit, the backtrace surface, and the acceptance failure that could print and still exit zero. Things they called done were not: the backend reports' no-plan buckets had gone stale in the other direction, the value-dependent defvar was superseded rather than built, and macro-expansion source locations are on an unmerged lane, so that entry is NEXT and names the branch. Every comment that cited one of the five by name now cites a heading that exists, in TODO.org or in docs/BUILT.md. The session reports under docs/handoffs/ keep naming the files they worked on, because rewriting them would falsify what those sessions did; each carries a note saying where the content went.
104 lines
4.5 KiB
Plaintext
104 lines
4.5 KiB
Plaintext
;;;; slurp and barf — TODO.org, "slurp and barf are the file surface".
|
|
;;;;
|
|
;;;; slurp reads a whole file and answers a (Vec u8). It allocates, which is
|
|
;;;; why it waited for Vec, and it follows spec-memory.md's rule to the letter:
|
|
;;;; no allocating operation returns an error, so there is no Result here and
|
|
;;;; no out-parameter anywhere.
|
|
;;;;
|
|
;;;; Failure signals a condition under a restart, which is the pattern
|
|
;;;; StorageExhausted set this session. Two restarts, and they are the pair
|
|
;;;; Common Lisp establishes for a file-error:
|
|
;;;;
|
|
;;;; retry the file may be there now
|
|
;;;; use-value [p string] try this other path instead
|
|
;;;;
|
|
;;;; use-value is a *typed* restart — the second thing this session bought —
|
|
;;;; and it is the first one the compiler itself emits. Its parameter is the
|
|
;;;; path slot the attempt reads, so the clause body is empty: the invoker's
|
|
;;;; argument lands in the slot, the clause falls through, and the loop
|
|
;;;; re-attempts against the new path.
|
|
|
|
;; Handlers cannot see the locals of the function that established them, so the
|
|
;; observations are globals — the same shape exhausted.flan uses.
|
|
(defonce seen i64)
|
|
(defonce last-reason i32)
|
|
(defonce last-op i32)
|
|
(defonce last-path string)
|
|
|
|
(defn main [] i32
|
|
;; ── The happy path ────────────────────────────────────────────────
|
|
(let [v (slurp "programs/assets/a.txt")]
|
|
(println (length v)) ; 13
|
|
(print (string (slice v))) ; hello from a
|
|
(free v))
|
|
|
|
;; Byte-exact, the same as an embed: nothing here decodes anything.
|
|
(let [v (slurp "programs/assets/raw.bin")]
|
|
(println (length v)) ; 4
|
|
(println (at v 0)) ; 0
|
|
(println (at v 2)) ; 255
|
|
(free v))
|
|
|
|
;; ── use-value: a missing file, answered with another path ─────────
|
|
;; The textbook case. The handler does not know what slurp was going to do
|
|
;; with the bytes and does not have to: it names a file that is there and
|
|
;; the read resumes as if that had been asked for all along.
|
|
(handler-bind
|
|
[(FileError [c]
|
|
(set seen (+ seen 1))
|
|
(set last-reason (.reason c))
|
|
(set last-op (.op c))
|
|
(set last-path (.path c))
|
|
(invoke-restart 'use-value "programs/assets/b.bin"))]
|
|
(let [v (slurp "programs/assets/does-not-exist")]
|
|
(println (length v)) ; 3
|
|
(println (string (slice v))) ; BBB
|
|
(free v)))
|
|
(println seen) ; 1
|
|
(println (= last-reason file-missing)) ; true
|
|
(println (= last-op file-op-read)) ; true
|
|
;; The condition carries the path that actually failed, not the one that
|
|
;; eventually worked — the handler is told what it is answering about.
|
|
(println last-path) ; programs/assets/does-not-exist
|
|
|
|
;; ── barf, and reading back what it wrote ──────────────────────────
|
|
(barf "slurp-out.txt" (bytes-view "round trip\n"))
|
|
(let [v (slurp "slurp-out.txt")]
|
|
(println (length v)) ; 11
|
|
(print (string (slice v))) ; round trip
|
|
(free v))
|
|
|
|
;; barf's own failure signals the same condition with op = write. A directory
|
|
;; that does not exist is the reachable case on every platform.
|
|
(set seen 0)
|
|
(handler-bind
|
|
[(FileError [c]
|
|
(set seen (+ seen 1))
|
|
(set last-op (.op c))
|
|
(invoke-restart 'use-value "slurp-out.txt"))]
|
|
(barf "no-such-dir/x.txt" (bytes-view "second\n")))
|
|
(println seen) ; 1
|
|
(println (= last-op file-op-write)) ; true
|
|
(let [v (slurp "slurp-out.txt")]
|
|
(print (string (slice v))) ; second
|
|
(free v))
|
|
|
|
;; ── retry: the file was not there, so the handler makes it ────────
|
|
;; The other restart, and the one use-value cannot stand in for: here the
|
|
;; path is right and the world is wrong. The handler fixes the world and
|
|
;; re-attempts the *same* request, which is exactly what retry means for a
|
|
;; failed allocation too.
|
|
(set seen 0)
|
|
(handler-bind
|
|
[(FileError [c]
|
|
(set seen (+ seen 1))
|
|
(set last-reason (.reason c))
|
|
(barf "slurp-made.txt" (bytes-view "made by the handler\n"))
|
|
(invoke-restart 'retry))]
|
|
(let [v (slurp "slurp-made.txt")]
|
|
(print (string (slice v))) ; made by the handler
|
|
(free v)))
|
|
(println seen) ; 1
|
|
(println (= last-reason file-missing)) ; true
|
|
0)
|