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.libraryform and nofrom:. A foreign function is found by the linker among the libraries the manifest's:nativelists (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.