Skip to the content
Diaspar

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:

  1. 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 familiar close.
  2. Automatic release at the last reference. When Perceus (D004) sees the last reference to a value that implements Release disappear, it calls release. Files close themselves, deterministically, unlike Python's __del__ or Java's finalizers.
  3. Released once. After release (through with, 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.
  4. with releases at the end of its block, even if references remain, for locks and transactions (D005).
  5. A failed release is never lost:
    • in with and defer, 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.
  6. 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 with or close to make the place of the error explicit.
  7. Cycles. Resources reachable only through cycles of cells are released by the cycle collector in an unspecified order (D004); use with when 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 a File and 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 second fs.read-line of an open file failed in compiled code.
  • A resource cannot be copied. assoc (and every update) on a value whose type implements Release changes 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 a Drop type to be Copy for 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 with block, 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, because release does not know whether the block ended normally; releasing without committing means discarding, the safe default (Go's renameio, Python's atomicwrites).
  • fsync of the directory after rename is part of commit, 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's f.Sync(); Python's os.fsync and fcntl.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.