Skip to content

FFI (Foreign Function Interface)

Overview

FFI allows Cera code to call C functions in shared libraries (DLLs on Windows, .so on Linux, .dylib on macOS) without requiring C++ compilation.

Declaring Extern Functions

Extern declarations must be inside an unsafe block:

unsafe {
extern("msvcrt") ccall int abs(int x);
extern("kernel32") stdcall uint32 GetCurrentProcessId();
}

Block Form

Multiple declarations from the same library:

unsafe {
extern("kernel32") {
stdcall uint32 GetCurrentProcessId();
stdcall void Sleep(uint32 ms);
stdcall uint32 GetTickCount();
}
}

Linkage Name Override

Use a second string argument to specify the C symbol name when it differs from the Cera function name:

unsafe {
extern("kernel32", "GetCurrentProcessId") stdcall uint32 GetPID();
}

Named Argument Syntax

Arguments can use lib: and func: labels in any order. func is optional:

unsafe {
extern(lib: "kernel32", func: "GetCurrentProcessId") stdcall uint32 GetPID();
extern(func: "GetCurrentProcessId", lib: "kernel32") stdcall uint32 GetPID2();
extern(lib: "msvcrt") ccall int abs(int x);
}

Calling Conventions

KeywordConvention
ccallC default (cdecl)
stdcallWindows stdcall
fastcallfastcall
syscallOS syscall

On 64-bit platforms, all conventions map to the platform ABI.

Safety

FFI has two layers of safety:

1. Declarations Require unsafe

// ERROR: Extern declarations require an unsafe block
extern("msvcrt") ccall int abs(int x);
// OK
unsafe { extern("msvcrt") ccall int abs(int x); }

2. Calls Require requires(caller: trusted)

unsafe { extern("msvcrt") ccall int abs(int x); }
// ERROR: caller must be declared 'requires(caller: trusted)'
int result = abs(-42);
// OK: wrap in a trusted function
int safeAbs(int x) requires(caller: trusted) {
return abs(x);
}
int result = safeAbs(-42);

This prevents untrusted user code from directly accessing native functions.

In addition to compile-time enforcement, the runtime re-checks the trust contract when an .asm is loaded: an assembly that contains extern call sites is rejected unless every calling function preserves its requires(caller: trusted) declaration. CLI flags can no longer grant blanket trust — a function must declare requires(caller: trusted) in source to be allowed to call into FFI.

Library Resolution

Libraries are resolved automatically with platform-appropriate extensions:

PlatformTries
Windowsname then name.dll
Linuxname then libname.so then name.so
macOSname then libname.dylib then name.dylib then libname.so then name.so

Error Handling

If a library or symbol cannot be found, calling the function at runtime throws an FFIException:

unsafe { extern("missing_lib") ccall int badFunc(); }
int test() requires(caller: trusted) {
try {
badFunc(); // throws FFIException
} catch (FFIException e) {
string msg = e.Message;
// "FFI error: cannot load 'badFunc' from library 'missing_lib'"
}
}

Examples

Cross-Platform C Runtime

unsafe {
extern("msvcrt") { // Windows
ccall int abs(int x);
}
// Linux: extern("libc") { ... }
// macOS: extern("libSystem") { ... }
}
int compute() requires(caller: trusted) {
return abs(-100); // returns 100
}

Windows API

unsafe {
extern("kernel32") {
stdcall uint32 GetCurrentProcessId();
stdcall void Sleep(uint32 ms);
}
extern("user32") {
stdcall int MessageBoxA(int hwnd, int text, int caption, uint32 flags);
}
}
void init() requires(caller: trusted) {
uint32 pid = GetCurrentProcessId();
Sleep(100);
}

Conditional Compilation

FFI support is controlled by the CERA_FFI CMake option (ON by default):

Terminal window
cmake -DCERA_FFI=OFF .. # disable FFI entirely

When disabled, extern declarations produce a compile error and all FFI code is excluded from the binary.