Principle:LaurentMazare Tch rs Generated FFI Bindings

Knowledge Sources	LaurentMazare_Tch_rs Rust FFI PyTorch Native Functions
Domains	Code Generation, Foreign Function Interface, Compiler Tooling
Last Updated	2026-02-08 00:00 GMT

Overview

Multi-layer generated FFI binding chains transform a canonical API specification through successive code generation stages, producing type-safe foreign function interfaces from C++ wrappers through C headers to target language extern declarations.

Description

When binding a library with hundreds or thousands of functions, a multi-layer generated binding chain automates the production of every layer in the FFI stack. Rather than writing C++ wrappers, C headers, and target language declarations by hand, a code generator reads the upstream API specification and emits all three layers simultaneously, ensuring perfect consistency.

The generation chain has distinct stages, each adding its own concerns:

Stage 1: C++ Wrapper Generation

From the API specification (e.g., a YAML file describing function signatures), the generator emits C++ wrapper functions that:

• Declare extern "C" linkage to prevent name mangling.
• Convert C-compatible argument types (opaque pointers, raw arrays) back into C++ types.
• Call the actual C++ library function.
• Catch any exceptions and store error messages in thread-local storage.
• Convert return values back to C-compatible types.

Stage 2: C Header Generation

For each C++ wrapper function, a corresponding C header declaration is emitted. This header:

• Declares the function with C linkage.
• Uses only C-compatible types in the signature.
• Serves as the contract between the C++ implementation and any language that can consume C headers.

Stage 3: Target Language Extern Block Generation

From the C headers (or directly from the specification), the generator emits the target language's FFI declarations:

• extern blocks (in Rust) or equivalent mechanism in other languages.
• Type mappings from C types to the target language's type system.
• Pointer types wrapped in the target language's safe abstractions.

The key benefit of generating all three layers from a single source is guaranteed consistency: if a function signature changes in the specification, all layers are updated simultaneously, eliminating the class of bugs caused by mismatched signatures across the FFI boundary.

Usage

Apply multi-layer FFI generation when:

• The API surface is large - Hundreds to thousands of functions make manual binding maintenance impractical.
• The API evolves frequently - Upstream releases add, modify, or deprecate functions regularly.
• Multiple binding layers exist - The C++ wrapper, C header, and target language declaration must all agree.
• Type safety is critical - Generated code can enforce type correctness at every layer, catching signature mismatches at compile time rather than runtime.
• Reproducibility is needed - The generation process should be deterministic and produce identical output for the same input specification.

Theoretical Basis

Generation Chain Architecture

The complete generation pipeline transforms a single input through multiple output stages:

INPUT: API Specification (YAML/JSON)
    |
    v
+---------------------------+
|   STAGE 1: C++ Wrappers   |
|   (.cpp files)             |
|   - extern "C" functions   |
|   - Exception catching     |
|   - Type marshaling        |
+---------------------------+
    |
    v
+---------------------------+
|   STAGE 2: C Headers       |
|   (.h files)               |
|   - Function declarations  |
|   - Opaque type typedefs   |
|   - C-compatible types     |
+---------------------------+
    |
    v
+---------------------------+
|   STAGE 3: Extern Blocks   |
|   (target language files)  |
|   - FFI declarations       |
|   - Safe type wrappers     |
|   - Link directives        |
+---------------------------+

Per-Function Generation Template

For a single function from the specification, the generator produces three coordinated outputs:

Given specification entry:

name: "add"
arguments: [self: Tensor, other: Tensor, alpha: Scalar]
returns: Tensor

Stage 1 output (C++ wrapper):

EXTERN_C void atg_add(tensor *out, tensor self, tensor other, scalar alpha):
    TRY:
        result = call_cpp("add", unwrap(self), unwrap(other), unwrap(alpha))
        out[0] = wrap(result)
    CATCH e:
        store_error(e.message)
        out[0] = NULL

Stage 2 output (C header):

DECLARE void atg_add(tensor *out, tensor self, tensor other, scalar alpha);

Stage 3 output (target language extern):

EXTERN FUNCTION atg_add(
    out: *mut tensor_ptr,
    self_: tensor_ptr,
    other: tensor_ptr,
    alpha: scalar_ptr
)

Naming Convention Transformation

Function names must be transformed to be valid and unambiguous across all three layers:

Failed to parse (syntax error): {\displaystyle \text{binding\_name} = \text{prefix} + \text{underscore\_join}(\text{name}, \text{overload})}

For example:

• Specification: add.Tensor becomes atg_add_tensor
• Specification: add.Scalar becomes atg_add_scalar
• Specification: add_ (in-place) becomes atg_add_

The prefix (e.g., atg_) provides a namespace to avoid collisions with other C symbols.

Return Value Strategies

Functions may return different types, requiring different marshaling strategies:

Return Type	C Strategy	Notes
Single tensor	Output pointer parameter	Caller allocates, callee fills
Multiple tensors	Output pointer array	Array of N pointers for N outputs
Scalar value	Direct return or output pointer	Depends on type size
Void (in-place)	No return value	Modifies input tensor directly

The output-pointer pattern (rather than returning by value) is preferred because:

1. It allows the error to be signaled by setting the output to null.
2. It avoids complications with returning structs across the C ABI on different platforms.
3. It naturally extends to multiple return values.

Consistency Verification

The generator can optionally emit verification checks:

FOR EACH function IN specification:
    cpp_signature = parse_cpp_wrapper(function)
    h_signature = parse_header(function)
    extern_signature = parse_extern_block(function)

    ASSERT cpp_signature.arg_types == h_signature.arg_types
    ASSERT h_signature.arg_types maps_to extern_signature.arg_types
    ASSERT cpp_signature.return_type == h_signature.return_type

This can be done at generation time (statically) or as a build step to catch any drift between layers.

Batch Generation Efficiency

When generating thousands of functions, the generator processes them in batch:

FUNCTION generate_all(specification):
    cpp_output = open_file("generated.cpp")
    h_output = open_file("generated.h")
    extern_output = open_file("generated_bindings")

    emit_headers(cpp_output, h_output, extern_output)

    FOR EACH function IN specification:
        cpp_output.write(generate_cpp_wrapper(function))
        h_output.write(generate_c_declaration(function))
        extern_output.write(generate_extern_declaration(function))

    emit_footers(cpp_output, h_output, extern_output)

This ensures all outputs are generated in a single pass, maintaining ordering consistency across files.

Related Pages

• Implementation:LaurentMazare_Tch_rs_Torch_Api_Generated_Cpp
• Implementation:LaurentMazare_Tch_rs_Torch_Api_Generated_H
• Implementation:LaurentMazare_Tch_rs_C_Generated_Rs