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
| Keyword | Convention |
|---|---|
ccall | C default (cdecl) |
stdcall | Windows stdcall |
fastcall | fastcall |
syscall | OS 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 blockextern("msvcrt") ccall int abs(int x);
// OKunsafe { 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 functionint 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:
| Platform | Tries |
|---|---|
| Windows | name then name.dll |
| Linux | name then libname.so then name.so |
| macOS | name 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):
cmake -DCERA_FFI=OFF .. # disable FFI entirelyWhen disabled, extern declarations produce a compile error and all FFI code is excluded from the binary.