Skip to content
EN FR

FPL to ABI bridge

Documentation status: architecture — see Maturity and evidence.

Purpose

The engine contains an execution bridge that allows a resolved FPL call to cross the native ABI boundary. This page documents the architectural behavior, not private implementation types.

flowchart LR
    FPL[FPL expression] --> LINK[ABI link resolution]
    LINK --> DESC[Method descriptor]
    FPL --> VALUES[FPL runtime values]
    VALUES --> CONVERT[ABI value conversion]
    DESC --> EXEC[ABI executor]
    CONVERT --> EXEC
    EXEC --> RESULT[ABI result]
    RESULT --> BACK[Convert to FPL value]

Current conversion subset

The currently inspected bridge converts FPL values to ABI arguments for:

  • integer / i32;
  • raw pointer;
  • ABI handle.

It converts ABI results back to FPL values for:

  • void;
  • integer / i32;
  • pointer;
  • handle.

Unsupported kinds fail explicitly rather than being reinterpreted.

Type checking

The bridge checks the FPL runtime value type against the ABI descriptor before execution. For example, an integer ABI parameter cannot silently accept a pointer runtime value. Nullable parameters also reject a missing value when nullability is false.

Receiver handling

An instance receiver is represented as an opaque pointer-valued FPL object. It is converted to the native receiver handle only at the ABI boundary.

Owned result tracking

When the ABI returns an owned handle, the bridge records the native result metadata associated with that pointer. Releasing the corresponding FPL value routes the release through the ABI executor and then clears the pointer.

The bridge also releases any still-owned tracked results when it is destroyed, providing a defensive cleanup path. Explicit release remains preferable for predictable lifetime.

Source-level tests

The current engine test suite goes beyond unit conversion tests. It compiles source expressions, links them through an ABI manifest, executes a native constructor or instance method, receives pointer/handle values, and releases owned results.

That makes the FPL-to-native path an implemented architectural capability rather than only a manifest design.

Public documentation boundary

The bridge is relevant to advanced developers because it proves that published native capabilities can participate in FPL execution. Private bridge class names, internal pointer wrappers, and implementation-language layouts are not part of the public contract.