Skip to the content
Diaspar

Decision D021 · accepted; the details in design/ffi.md (2026-11-18, by delegation)

Calling C (FFI) is built in, in the Diaspar implementation

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) for the direction; the details accepted (2026-11-18, decided by the FFI agent on the author's delegation) in design/ffi.md, which replaces the proposals of "What it needs" below where they differ

Decision

Diaspar calls C libraries out of the box, through an explicitly imported module (std.ffi), and comes with a generator that produces wrapper packages from C libraries. FFI is built in the Diaspar implementation, not in the phase-0 interpreter (D012): the Rust interpreter would need the libffi crate, an external dependency with a C part, for a feature the throwaway host does not need.

Why it is cheaper here than in most languages

  • The backend emits C (D003): a foreign call in compiled code is a call in the generated text, and the C compiler handles calling conventions, struct layout, and platform ABIs.
  • Perceus does not move objects (D004): a pointer passed to C stays valid while its count is above zero; no pinning, unlike moving collectors in Java, C#, or Go.
  • Releasing C resources fits the memory model: when the last reference to a wrapper of sqlite3* disappears, its release function runs, as files close themselves (D005).

The design (2026-11-18)

design/ffi.md holds the design and its state: the declarations of std.ffi, the types, ownership through Release, the Unsafe effect, the generator diaspar bind, the REPL, and the questions left open. What changed against the table below:

  • Conversion at the boundary. A C struct is a Diaspar struct, an enum an enum, a bitmask a set, an out-parameter a result, an array with its count a vector; no Diaspar value is a view of C memory.
  • No ffi.library form and no from:. A foreign function is found by the linker among the libraries the manifest's :native lists (D025); the declaration names no library.
  • Ownership is not stated in the declaration. A handle owns nothing; a resource is a struct that implements Release (D023) and holds the handle.
  • No libffi, in the REPL either. The compiler emits a C stub per declared function; the REPL compiles the same stub into a shared object and loads it with dlopen.
  • The generator is diaspar bind, over clang's JSON AST, its input in the manifest's :bind; generated bindings are committed.
  • Blocking calls stay as D035 has them (blocking: true).

The example below shows the direction as it was proposed; design/ffi.md section 1 has the forms as accepted.

What it needs (proposed, 2026-11-15)

Part Proposal
Declarations Foreign functions declared in Diaspar with C types
Types i8…u64, f32/f64, pointers, UTF-8 nul-terminated strings; structs by value, arrays, enums, unions, and variadics later
Ownership Borrowed or owned pointers stated in the declaration; release functions run by Perceus
Safety Only through std.ffi; every foreign call performs an Unsafe effect, so limited sessions can forbid it (D020) and inference shows which functions reach C
Callbacks C calling Diaspar functions through trampolines, including from foreign threads (D006); later
Blocking calls Declared blocking: true: the worker hands its scheduling slot to another thread for the call, as Go does for system calls; a fiber with a C frame on its stack resumes only on its own thread; libraries bound to one thread get a pinned fiber (D035; design/concurrency.md §5.5)
Errors and effects Unwinding never crosses C frames: an error inside a callback is handled before returning to C; return codes and errno become typed errors
The REPL Dynamic calls through dlopen/dlsym and a call mechanism such as libffi, so a library can be loaded and called live
The binding generator Produces a wrapper package from a C library's headers, as Zig's @cImport or Ferron's anvil ffi gen; needs a C parser, usually libclang
Building Static and dynamic libraries, pkg-config, native dependencies declared in packages
(use std.ffi as: ffi)

(ffi.library sqlite "libsqlite3.so.0")
(ffi.defn sqlite3-open  [(path :c-string) (db (:out (:ptr Sqlite3)))] :i32 from: sqlite)
(ffi.defn sqlite3-close [(db (:ptr Sqlite3))] :i32 from: sqlite)

First version: hand-written declarations, scalar types, pointers, and strings, calls from compiled code and from the REPL, the Unsafe effect, and release through Perceus. Later: structs by value, callbacks, the binding generator, native dependencies in packages.