Decision D023 · accepted
Resources are released through one protocol, automatically or explicitly
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15)
Decision
One protocol, Release, says how a value gives back what it holds: a file descriptor, a lock, a connection, a GPU buffer, a C handle (D021).
(defprotocol Release
(release [x]))
(extend-type File Release
(release [f] (close-fd f.fd)))
;; shorthand for wrappers of C handles: the same in one line
(deftype Db [handle] opaque: true release: sqlite3-close)
Rules:
- One protocol for everything:
with,:release, and automatic release. The general name fits locks and handles as well as files; a file also offers the familiarclose. - Automatic release at the last reference. When Perceus (D004) sees the last reference to a value that implements
Releasedisappear, it callsrelease. Files close themselves, deterministically, unlike Python's__del__or Java's finalizers. - Released once. After
release(throughwith,defer, or a direct call) the value is marked released. Releasing again does nothing; using a released value is a clear error ("file opened at app.dias:3 is closed"); automatic release skips released values. withreleases at the end of its block, even if references remain, for locks and transactions (D005).- A failed release is never lost:
- in
withanddefer, D005's table applies; - an automatic release that fails raises its error where the last reference disappeared, with context: "while releasing File (opened at app.dias:3) automatically"; if another error is already unwinding at that point, it goes to
:suppressed.
- in
- A hint for resources whose errors matter. Automatic release happens wherever the last reference goes, so for a file that was written (where a failed close means lost data) the compiler suggests
withorcloseto make the place of the error explicit. - Cycles. Resources reachable only through cycles of cells are released by the cycle collector in an unspecified order (D004); use
withwhen the order matters.
When a resource is released, and copies of resources (accepted, 2026-11-18)
- A call keeps its arguments until it returns. A resource whose last use is an argument of a call is released after that call returns, not while it runs; a function that takes the resource apart (
std.fs's functions match aFileand pass its handle to a primitive) can therefore use it to its end. This is the one rule of release at last use (D026 [7]), the same in the interpreter, compiled code and the evaluator; it replaces the three rules the runtime had (runtime/README.md, deviation 9). It is Rust's rule that temporaries live to the end of the statement, applied to calls. Found by the review of 2026-11 (B1, S2): the secondfs.read-lineof an open file failed in compiled code. - A resource cannot be copied.
assoc(and every update) on a value whose type implementsReleasechanges it in place when the value is unique; when it is shared, it raises "a resource cannot be copied: it is shared", since two copies would release one handle twice. Rust forbids aDroptype to beCopyfor the same reason. Found by the review (B2: the copy wrote past the end of the object).
Locks, atomic files and syncing (accepted, 2026-11-16)
Everything that holds something is a value implementing Release, used with the one general with (D005). There are no with-lock-style helpers per resource.
(with [l (fs.lock path)] ; exclusive advisory lock (flock), released at the end of the block
(update-cache …))
(with [l (fs.lock path shared: true)] …) ; shared, for readers
(with [l (fs.lock path wait: false)] …) ; do not wait: a held lock raises LockBusy
(fs.write-atomic path text) ; temporary file in the same directory → fsync → rename → fsync of the directory
(with [f (fs.atomic-file path)] ; streaming atomic write
(io.write f header)
(io.write f body)
(fs.commit f)) ; makes it durable and visible
;; released without commit (an error, an early exit): the temporary file is removed, the old file is untouched
(fs.sync f) ; fsync: data and metadata on disk
(fs.sync f data-only: true) ; fdatasync
- A lock is released at the end of its
withblock, not at the last reference (rule 4), since a lock must not outlive the code it protects. Locks are advisory, as everywhere on Unix: they protect against processes that ask for them. - An atomic file needs an explicit
fs.commit, becausereleasedoes not know whether the block ended normally; releasing without committing means discarding, the safe default (Go'srenameio, Python'satomicwrites). fsyncof the directory afterrenameis part ofcommit, so a crash leaves either the old file or the new one, never a mix or a lost rename.- Prior art: Rust's
File::sync_all,sync_data,lock,lock_shared,try_lock; Go'sf.Sync(); Python'sos.fsyncandfcntl.flock.
Why
Rust's Drop cannot return an error, so a failed close of a File is silently lost, and Go's Close errors are routinely ignored. Python's with, C#'s using, and Java's try-with-resources make release explicit but rely on unpredictable finalizers otherwise. Reference counting gives deterministic automatic release, and effects let it raise an error.