Language Features /docs/ffi

Foreign Function Interface

Foreign Function Interface ( @extern )

@extern is Cure's foreign-function interface. It lets a Cure function stand in for a function that lives outside Cure — anything callable on the BEAM: Erlang/OTP modules ( :erlang , :io , :math , ...), Elixir modules, AtomVM NIFs, or hand-written Cure.*.Builtins helpers.

An @extern function is a type-only signature . You declare its name and types; the compiler trusts those types and lowers every call to a direct BEAM remote call. There is no Cure implementation to compile — the implementation is the external function.

@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int

Calling abs(-42) at runtime invokes erlang:abs(-42) .

Syntax

@extern(<module>, <function>, <arity>)
<visibility?> fn <name>(<typed params>) -> <ReturnType>

The decorator takes exactly three arguments:

Argument Meaning Examples
The target BEAM module :erlang , :io , :math , Elixir.MyApp.Native
The target function name (an atom) :abs , :put_chars , :fsm_spawn
The function's arity; must equal the number of parameters in the head 0 , 1 , 2

Module names

  • Erlang / OTP modules are written as plain atoms: :erlang , :io , :math , :lists , :maps .
  • Elixir modules are written with their fully qualified dotted path under the Elixir. namespace: Elixir.MyApp.Native , Elixir.Enum . The parser converts the dotted path into the underlying module atom ( :"Elixir.MyApp.Native" ) for you.

Visibility

@extern composes with the local keyword, exactly like a normal function, to make the FFI binding private to its module:

@extern(:erlang, :integer_to_binary, 1)
local fn int_to_string(n: Int) -> String

The two rules

A foreign function is opaque to the compiler. Two invariants keep the FFI sound and honest; both are enforced at type-check time.

  1. The head must be fully typed ( E056 )

Every parameter must carry a type annotation and a return type must be declared. The compiler cannot see the external implementation, so the declared types are the only contract it has. Without them the signature would silently default to Any and the type checker would be blind at every call site.

# rejected (E056): parameter `x` and the return type are missing
@extern(:erlang, :abs, 1)
fn abs(x)
@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int

A zero-parameter extern still needs its return type:

@extern(:math, :pi, 0)
fn pi() -> Float

  1. The declaration must not have a body ( E057 )

An @extern function has no Cure body. Codegen lowers it to a direct remote call, so anything you write as a body is dead code — never compiled, never run. To stop that silent discard from misleading a reader, a body is an error. This applies to both body forms: a = ... body and a multi-clause | definition.

# rejected (E057): the `= x` body is ignored by codegen
@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int = x
# rejected (E057): multi-clause bodies are ignored too
@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int
  | 0 -> 0
  | n -> n
@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int

If you need local logic, write a normal function and call the extern from inside it:

@extern(:erlang, :abs, 1)
fn raw_abs(x: Int) -> Int

fn abs_or_zero(x: Int) -> Int =
  pickup
    x < -1000 -> 0
    else      -> raw_abs(x)

Run cure explain E056 or cure explain E057 for the in-tool reference.

How it lowers

An @extern function compiles to a thin wrapper whose body is a single remote call. For:

@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int

codegen emits the Erlang equivalent of:

abs(X) -> erlang:abs(X).

The parameters are passed straight through to the target function in order. The wrapper's arity is the number of parameters in the Cure head.

Type checking and trust

The compiler trusts an @extern signature; it does not verify the declared types against the real external function (it cannot — the function is outside Cure). At call sites, callers are checked against the declared head as if it were any other Cure function. The responsibility for matching the external function's true contract is yours.

A practical consequence: keep the declared types as precise as the external function actually guarantees. An overly wide type ( Any ) propagates imprecision into every caller; an overly narrow one invites runtime surprises the checker will not catch.

Effects

An earlier version of the compiler inferred a per- @extern effect kind ( :io , :state , :spawn , :extern , ...) from the target module, as part of the classic type checker's effect-tracking pass ( Cure.Types.Effects , added in v0.15.0). That pass was removed along with the rest of the classic checker and code generator; the current dependent pipeline does not classify @extern calls by target module or effect kind. The REPL's :effects expr command reports only a coarse pure-vs-effectful verdict based on whether expr 's inferred type is the kernel's Effect(T) type former.

Examples

Erlang stdlib:

@extern(:erlang, :abs, 1)
fn abs(x: Int) -> Int

@extern(:math, :sqrt, 1)
fn sqrt(x: Float) -> Float

@extern(:io, :put_chars, 1)
fn print(s: String) -> Atom

Elixir helpers (note the dotted Elixir. module path):

@extern(Elixir.MyApp.Native, :read_counter, 1)
fn read_counter(key: Atom) -> Int

The same name may be bound at several arities, each its own @extern :

@extern(Elixir.MyApp.Native, :get_env, 2)
fn get_env(name: Atom, key: Atom) -> Any

@extern(Elixir.MyApp.Native, :get_env, 3)
fn get_env(name: Atom, key: Atom, default: Any) -> Any

Runtime availability

@extern is resolved at runtime by the BEAM, not at compile time by Cure. The target module and function must exist on the VM that runs the compiled code. A signature that compiles fine against :re or :httpc , for example, will still fail at runtime on a VM (such as AtomVM) that does not ship those modules. When targeting a constrained runtime, confirm the external function is present there.

Related