Principle:LaurentMazare Tch rs C FFI Bridge

Knowledge Sources	LaurentMazare_Tch_rs Rust FFI Guide C++ ABI Issues
Domains	Foreign Function Interface, Systems Programming, Language Interoperability
Last Updated	2026-02-08 00:00 GMT

Overview

A C Foreign Function Interface (FFI) bridge connects two languages by exposing C-compatible function signatures as an intermediate layer, enabling a high-level language to call into a C++ library while maintaining memory safety and error propagation.

Description

When a high-level language (such as Rust, Python, or Go) needs to use functionality from a C++ library (such as a deep learning framework), direct interoperability is difficult because C++ has features (name mangling, exceptions, templates, classes) that other languages cannot directly consume. The solution is a C FFI bridge -- a thin layer of C-compatible functions that wraps the C++ API.

The bridge has three layers:

1. C++ Wrapper Layer

This layer contains functions with extern "C" linkage that:

Accept and return only C-compatible types (pointers, integers, floats, arrays).
Wrap C++ objects (tensors, modules) behind opaque pointers (typically void*).
Catch C++ exceptions and convert them into an error reporting mechanism compatible with C.
Perform any necessary type conversions between C++ types and their C representations.

2. C Header Layer

This layer provides the function declarations that the calling language uses to generate its foreign function bindings. The header defines:

The opaque pointer types.
All function signatures with C-compatible parameter and return types.
Any necessary preprocessor definitions or constants.

3. Calling Language Bindings

This layer declares extern functions matching the C header signatures, using the calling language's FFI mechanism. It adds:

Type-safe wrappers around opaque pointers (newtype pattern).
Automatic resource management (destructors, drop traits).
Idiomatic error handling translated from the C error mechanism.

Error Propagation via Thread-Local Storage

A critical design challenge is error propagation. C++ exceptions cannot cross the C ABI boundary safely. The standard solution is:

The C++ wrapper catches all exceptions in a try/catch block.
On exception, the error message is stored in thread-local storage (TLS).
The function returns a sentinel value (null pointer, error code) to indicate failure.
The calling language checks the return value, and if it indicates failure, reads the error message from thread-local storage.

Thread-local storage is essential because it is thread-safe -- concurrent FFI calls from different threads will not overwrite each other's error messages.

Usage

Apply the C FFI bridge pattern when:

Binding a C++ library to a language that only supports C-level FFI (most languages).
Wrapping complex C++ types that have no direct representation in the target language.
Propagating errors across the language boundary without undefined behavior.
Maintaining memory safety by ensuring all C++ objects are properly constructed and destructed through the bridge.
Isolating ABI concerns so that changes to the C++ library's internal layout do not break the calling language's bindings.

Theoretical Basis

Opaque Pointer Pattern

C++ objects are represented in C as opaque pointers:

// C++ side: actual object
class Tensor { /* ... fields, methods ... */ };

// C bridge: opaque handle
typedef void* tensor_handle;

The handle is created by allocating the C++ object and casting to void*, and recovered by casting back. This hides all C++ implementation details from the C interface.

CREATE(args):
    object = new CppObject(args)
    RETURN cast_to_opaque(object)

USE(handle, method, args):
    object = cast_from_opaque(handle)
    RETURN object.method(args)

DESTROY(handle):
    object = cast_from_opaque(handle)
    delete object

Exception-to-Error Translation

The canonical pattern for catching C++ exceptions at the FFI boundary:

THREAD_LOCAL error_message = ""

FUNCTION ffi_wrapper(args...) -> result_type:
    TRY:
        result = call_cpp_function(args...)
        RETURN result
    CATCH exception AS e:
        error_message = e.what()
        RETURN ERROR_SENTINEL   // e.g., null pointer, -1

FUNCTION get_last_error() -> string:
    msg = error_message
    error_message = ""
    RETURN msg

The calling language then follows this protocol:

result = ffi_wrapper(args...)
IF result == ERROR_SENTINEL:
    error_msg = get_last_error()
    RAISE language-appropriate error with error_msg

Memory Management Protocol

Every C++ object created through the bridge must have a corresponding destruction function:

// For each type exposed through the bridge:
FUNCTION type_create(args...) -> handle
FUNCTION type_destroy(handle) -> void

// The calling language wraps this in RAII / destructor:
STRUCT SafeHandle:
    raw: opaque_pointer

    ON_DROP:
        type_destroy(self.raw)

This ensures that C++ objects are freed even if the calling language encounters errors, preventing memory leaks.

Type Mapping Table

C++ Type	C Bridge Type	Calling Language Type
`at::Tensor`	`void*` (tensor handle)	Newtype wrapper around raw pointer
`std::string`	`const char*`	Native string type
`std::vector<int64_t>`	`int64_t* data, int len`	Slice/array type
`c10::optional<T>`	`T value, int is_null`	Optional/nullable type
`bool`	`int` (0 or 1)	Native boolean
`double`	`double`	Native float
`int64_t`	`int64_t`	Native integer
C++ exception	Thread-local string	Language error/exception type

Thread Safety Considerations

The FFI bridge must be thread-safe:

Thread-local error storage ensures concurrent FFI calls do not corrupt each other's error messages.
Object handles can be used from any thread (assuming the underlying library supports it), but must not be used concurrently from multiple threads unless the library explicitly supports concurrent access.
Global state (such as library initialization) must be protected by synchronization primitives and should use call-once semantics.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment