Foreign Function Interface

FFI is design-stage in the source corpus. There are no runnable Stage-0 FFI examples under .sources/vela/examples. This page documents the planned model from design/FFI.md and design/MODULES_AND_PACKAGES.md.

1. Boundary model

The design separates two kinds of interop:

• code interop: calling or exporting foreign functions,
• data interop: sharing columns and dataframes through Arrow buffers.

The planned rule is that foreign code calls are fenced behind unsafe, while safe Vela wrappers expose ordinary Result-returning APIs.

2. Planned C ABI lane

The design uses extern "C" declarations for foreign functions and pub extern "C" for functions exported from Vela. Only C-ABI-safe types are planned to cross directly: fixed-width numeric primitives, raw pointers, #[repr(C)] structs, and handles. Vela String, Vec, and DataFrame are planned to cross as handles or Arrow data, not by value.

The source design shows this shape:

extern "C":
    fn ZSTD_compressBound(srcSize: USize) -> USize
    fn ZSTD_compress(dst: *mut U8, dstCap: USize,
                     src: *const U8, srcSize: USize, level: I32) -> USize
    fn ZSTD_isError(code: USize) -> U32

That syntax is planned. It is not runnable in the current Stage-0 interpreter.

3. Planned ownership across FFI

The design uses reference counting plus lifecycle hooks to manage foreign resources:

• =destroy releases an owned foreign handle,
• =sink transfers ownership without a copy,
• =copy defines copy behavior or rejects copying for unique handles.

The planned safety contract is:

• panics do not cross C boundaries,
• each allocator frees its own allocations,
• raw pointer dereferences and pointer casts are unsafe,
• exported APIs catch failures at the boundary and translate them to C-compatible error signals.

4. Planned Python and R interop

Python interop is planned around embedded CPython, a PyObject bridge, and Arrow zero-copy data exchange. Python exceptions become Err(PyError) values. Operations on Python objects require a GIL/attach scope in the design.

R interop is planned around embedded libR, SEXP handles, PROTECT / release discipline, and Arrow zero-copy exchange with R Arrow or nanoarrow. R errors are planned to surface as Err(RError).

5. Planned JS/WASM interop

The WASM design exports Vela functions with generated JS/TypeScript glue. Primitive numbers cross directly, strings copy through linear memory, typed arrays can view WASM memory for a bounded lifetime, and richer values use handles or Arrow buffers.

6. Packaging knobs

The module/package design proposes manifest sections such as [ffi.c], [ffi.python], and build scripts such as build.vela. These are planned packaging features and should not be presented as available Stage-0 tooling.