Skip to content

Volume 18: Foreign Function Interface

1. Introduction

This volume defines the foreign function interface direction in the Rethon programming language. It describes the FFI model, foreign declarations, external functions, external types, primitive type mapping, string and buffer interop, pointer-like values, ownership across FFI boundaries, error handling across FFI boundaries, memory safety boundary, unsafe FFI operations, module and import interaction, standard library FFI support, platform considerations, package and RETPAK interaction, future extensions, and summary.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define ABI layout, calling-convention minutiae, linker formats, symbol-resolution internals, or platform-specific binary interface details. It defines the source-level direction for interoperability with external native libraries.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical. It is statically typed, AOT compiled, memory-safe by default, ownership-transparent, and suitable for native interoperability.

FFI shall allow Rethon code to interoperate with external native libraries while keeping ordinary Rethon code safe by default.

2. FFI Model

FFI shall be supported.

FFI shall be explicit.

Foreign declarations shall be source-visible and shall not be inferred implicitly from ordinary declarations.

The source-level FFI model shall define the boundary between safe ordinary Rethon code and external native code.

Ordinary Rethon code shall remain safe by default.

The FFI model shall favor typed wrappers, explicit ownership declarations, and conservative interoperability over hidden runtime magic.

Example:

foreign module c_math:
    foreign def sqrt(value: float) -> float

The FFI model shall support native interoperability without exposing manual memory management to ordinary safe code.

The specification shall define guarantees and boundaries rather than prescribing implementation details.

3. Foreign Declarations

Foreign declarations shall be explicit.

A foreign declaration shall identify a declaration whose implementation is provided outside ordinary Rethon source code.

Example:

foreign module c_stdio:
    foreign def puts(text: c_string) -> int

A foreign declaration shall be statically typed.

A foreign declaration shall use source-level type information to describe the values that cross the boundary.

Foreign declarations shall be limited to the interoperability surface.

A foreign declaration shall not imply that ordinary source code may ignore the language's safety rules.

4. External Functions

External functions shall be supported.

An external function shall be a function whose body is provided by an external native library.

Example:

foreign def strlen(text: c_string) -> int

An external function shall declare its parameter and return types explicitly.

An external function shall be callable from Rethon code through the ordinary typed call model once its boundary requirements are satisfied.

An external function shall not be assumed to follow Rethon memory or error semantics unless the FFI declaration says so.

External function declarations shall remain conservative and readable.

5. External Types

External types shall be supported.

An external type shall represent a type defined outside ordinary Rethon source code.

Example:

foreign struct CPoint:
    x: int
    y: int

External types shall be statically typed at the source level.

An external type shall be usable in FFI declarations, typed wrappers, and other interoperability contexts permitted by the language.

An external type shall not be assumed to follow Rethon value semantics unless the declaration or wrapper model explicitly states that behavior.

External types shall remain explicit and shall not be conflated with ordinary Rethon structs or classes.

6. Primitive Type Mapping

Primitive type mappings across FFI boundaries shall be explicit and statically checked where practical.

The source language shall define the mapping at the type level rather than by hidden inference.

Example:

foreign def add_i32(a: int32, b: int32) -> int32

The exact mapping of primitive types to foreign machine-level forms shall be platform- and implementation-dependent, but the source-level contract shall remain explicit.

Rethon shall not expose backend-specific integer widths, floating-point ABI details, or calling-convention layout in this volume.

Primitive mappings shall be conservative and shall not surprise safe ordinary code.

7. String and Buffer Interop

String and buffer interop shall be explicit.

The language shall not assume that native libraries accept or produce Rethon str values directly without a declared conversion boundary.

Example:

foreign def c_print(text: c_string) -> int

String interop shall distinguish between Rethon text values and foreign string or buffer representations.

Buffer interop shall be explicit and shall use typed source-level forms that make ownership and lifetime expectations visible.

The specification does not define a single universal foreign string or buffer layout.

String and buffer adapters may be provided by the standard library or by RETPAK packages.

8. Pointer-Like Values

Pointer-like values shall be supported only as explicit interoperability forms.

Pointer-like values shall not become the ordinary programming model for Rethon.

Example:

foreign type c_pointer<T>

Pointer-like values shall be treated as boundary types whose use is constrained by the memory model and FFI rules.

Pointer-like values shall not imply ordinary ownership semantics, and they shall not be used to reintroduce manual memory management into safe application code.

Pointer-like values shall remain explicit and isolated.

9. Ownership Across FFI Boundaries

Ownership transfer across FFI boundaries shall be explicit.

A foreign declaration shall state ownership expectations clearly enough for the source-level contract to be understandable.

The FFI model shall not expose retain/release to ordinary safe code.

Ordinary code shall not be required to perform manual memory management simply because it crosses an FFI boundary.

If a foreign API requires transfer of ownership, that transfer shall be represented in the source-level contract and shall be wrapped or isolated so that safe Rethon code remains ownership-transparent.

10. Error Handling Across FFI Boundaries

Error handling across FFI boundaries shall be explicit.

Foreign APIs may signal failure through return codes, out parameters, error objects, or other externally defined mechanisms, but the Rethon source contract shall make the error model visible.

Example:

foreign def c_open(path: c_string) -> Result<c_handle, Error>

Rethon code shall be able to map external failure conventions into Result<T, E>, Option<T>, raise, or other explicit error forms defined by the language.

The FFI layer shall not hide error conventions from ordinary source code.

11. Memory Safety Boundary

The FFI boundary shall preserve memory safety by default.

Safe Rethon code shall remain safe even when it calls foreign code through a properly declared boundary.

The language shall distinguish between safe wrappers and lower-level foreign operations that may require extra care.

A foreign declaration shall not weaken the safety guarantees of unrelated ordinary code.

The specification does not require all FFI interactions to be fully safe without additional constraints, but it does require that unsafe behavior be isolated and explicit.

12. Unsafe FFI Operations

Unsafe FFI operations shall be deferred and isolated into future explicit unsafe features.

The initial FFI direction shall not expose unsafe memory manipulation as ordinary source-level programming.

Operations involving raw pointer dereference, unchecked lifetime promises, unchecked ownership transfer, or similar hazards shall not be treated as part of the safe ordinary model.

If future language work introduces explicit unsafe constructs, FFI operations that cannot be proven safe shall be confined to those constructs.

13. Module and Import Interaction

FFI declarations shall participate in the module and import model.

Foreign declarations shall be placed in modules and imported like other declarations.

Example:

from native.math import sqrt

Modules shall remain the source-level namespace boundary for FFI declarations.

Foreign modules shall not require special import syntax unless a later specification introduces one for a clearly justified reason.

14. Standard Library FFI Support

The standard library may provide minimal, general-purpose FFI support utilities.

Such utilities may include foreign-string adapters, buffer wrappers, handle types, error translation helpers, and other conservative interoperability aids.

The standard library shall not turn FFI into a domain framework.

Higher-level bindings shall be provided by RETPAK packages when the domain is specialized or platform-specific.

15. Platform Considerations

Platform-specific behavior shall be isolated from the source-level FFI contract.

The specification does not commit to a single platform ABI model in this volume.

Platform differences shall be handled by implementation details, build configuration, or package-layer adaptation rather than by changing the ordinary source-level FFI model.

Source code that uses FFI shall remain readable and portable in its source-level intent even when platform bindings differ.

16. Package and RETPAK Interaction

Native bindings may be distributed through RETPAK packages.

RETPAK packages shall be the preferred distribution vehicle for domain-specific or platform-specific native bindings that are not part of the core standard library.

The FFI volume defines the language boundary; RETPAK defines the distribution boundary.

Native bindings packaged through RETPAK shall still obey the source-level FFI rules established in this volume.

17. Future Extensions

This volume defines the current direction for FFI in Rethon, but future specification work may refine the model in carefully controlled ways.

Possible future extensions include:

  • richer foreign type adapters
  • more explicit ownership annotations at the boundary
  • standard-library wrappers for common native conventions
  • broader buffer and string interoperability helpers
  • additional platform-specific binding support in RETPAK packages
  • explicit unsafe FFI constructs if justified later
  • tooling support for generating or validating bindings

Any future extension shall preserve the current direction:

  • FFI remains explicit
  • ordinary code remains safe by default
  • primitive mappings remain explicit and statically checked where practical
  • string and buffer interop remain explicit
  • ownership transfer remains declared, not hidden
  • error handling remains explicit
  • platform-specific behavior remains isolated
  • core unsafe memory behavior remains deferred and isolated
  • native bindings may be distributed through RETPAK packages

18. Summary

FFI shall be supported in Rethon.

FFI declarations shall be explicit, typed, and conservative.

Ordinary Rethon code shall remain safe by default, and unsafe FFI operations shall be isolated into future explicit unsafe features.

Primitive mappings, string and buffer interop, ownership transfer, and error handling across FFI boundaries shall all be explicit source-level concerns.

Platform-specific details shall remain isolated from the language's core source contract.

Native bindings may be distributed through RETPAK packages.

Rethon's FFI model shall therefore support native interoperability while preserving the language's Python-first, statically typed, memory-safe, ownership-transparent design.