Joseph Ferano
f88ce56073
Decisions 2 and 5. slurp allocates, which is why it waited for Vec, and it follows spec-memory.md's rule exactly: no allocating operation returns an error, so there is no Result here and no out-parameter. A failure to allocate is StorageExhausted under retry; a failure to read is FileError under retry and use-value. The two guards nest rather than merge, because they are two different failures with two different answerable questions — the handler that grows an arena is not the handler that supplies another path. The restarts are the pair Common Lisp establishes for a file-error. use-value is a typed restart, the other thing that landed this session, and this is the first one the compiler itself emits with a parameter. Its parameter *is* the path slot the attempt reads, so the clause body is empty: emit.ml's bind_params stores the invoker's argument into the slot, the clause falls through, and the loop re-attempts against the new path. Everything is inside that loop, so a use-value naming a different file re-measures it and re-allocates for its size; the Vec is freed at the top of each turn, which is why a retry does not leak. The host ABI grows by three calls and one reason reader: flan_file_size, flan_file_read, flan_file_write, flan_file_fail_reason. They are POSIX-shaped and Vec-ignorant — no handle crosses the boundary and nothing is held between calls — so a second target implements three functions. flan_slurp_into is runtime glue on this side of the ABI rather than a fourth call. These do touch paths, which is the widening plan.org names as the #1 portability risk and which decision 2 took knowingly; embed is the answer that does not touch them at all.
104 lines
4.4 KiB
Plaintext
104 lines
4.4 KiB
Plaintext
;;;; slurp and barf — NEXT.md decisions 2 and 5.
|
|
;;;;
|
|
;;;; 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.
|
|
(defvar seen i64)
|
|
(defvar last-reason i32)
|
|
(defvar last-op i32)
|
|
(defvar last-path string)
|
|
|
|
(defn main [] i32
|
|
;; ── The happy path ────────────────────────────────────────────────
|
|
(let [v (slurp "programs/assets/a.txt")]
|
|
(println (len v)) ; 13
|
|
(print (string (as-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 (len 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 (len v)) ; 3
|
|
(println (string (as-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 "round trip\n"))
|
|
(let [v (slurp "slurp-out.txt")]
|
|
(println (len v)) ; 11
|
|
(print (string (as-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 "second\n")))
|
|
(println seen) ; 1
|
|
(println (= last-op file-op-write)) ; true
|
|
(let [v (slurp "slurp-out.txt")]
|
|
(print (string (as-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 "made by the handler\n"))
|
|
(invoke-restart 'retry))]
|
|
(let [v (slurp "slurp-made.txt")]
|
|
(print (string (as-slice v))) ; made by the handler
|
|
(free v)))
|
|
(println seen) ; 1
|
|
(println (= last-reason file-missing)) ; true
|
|
0)
|