Skip to content

Externs

An extern declaration tells Gale how to call or describe code outside Gale. The declaration is a trusted contract: Gale checks its callers against the signature, but cannot prove that the native implementation keeps that promise.

A function extern names a native target and declares its Gale signature:

Typed declaration for a native text function. Gale callers use clean or trim.

mod externs.text
pub extern "String.trim" trim(value: String) -> String
pub fn clean(value: String) -> String {
trim(value)
}
pub extern type ForeignRef
pub extern ":erlang.make_ref" reference() -> ForeignRef

Gale emits String.trim(value) directly at each call site. The extern generates no wrapper module, function or @spec. The native target keeps its full name in generated Elixir; a Gale alias cannot redirect it. Erlang functions use spellings such as ":erlang.send". For a public Gale API with a spec, declare the extern privately and write a public fn, like clean above.

With runtime typechecks enabled (the default in :test), Gale checks extern arguments and return values at the call site; ordinary builds omit those checks. Declared types remain your responsibility when the native shape is one Gale cannot infer.

If a native function may raise an expected exception, say so. extern raises requires a Result return type and adapts every call: a normal return becomes Ok, each declared exception becomes Error:

Expected native exceptions become typed Result errors. An explicit native contract is trusted; Gale proves the wrapper and its callers against it.

mod externs.numbers
pub extern exception "ArgumentError" ArgumentError {
message: String
}
extern raises "String.to_integer" to_integer_native(value: String) -> Result<Integer, ArgumentError>
pub fn to_integer(value: String) -> Result<Integer, ArgumentError> {
to_integer_native(value)
}

Foreign exceptions can also be constructed with %ArgumentError{message: "invalid"}, returned inside Error, matched, and updated like ordinary structs. Construction uses the native struct defaults and sets the declared fields; it does not invoke a custom native exception/1 factory. Bind that factory explicitly with extern when required. Constructing a value never raises it.

The error union must name Gale-defined or extern exception types. Other exceptions are reraised; exits and throws are not caught. The private extern converts; the public to_integer gives Elixir callers a named, spec’d API.

An extern can declare a contract. Gale uses it when proving callers, but the native contract remains a trusted assumption:

extern pure ":erlang.abs" absolute(value: Integer) -> Integer
ensures { result == if value < 0 { -value } else { value } }
pub pure fn magnitude(value: Integer) -> Integer
ensures { result >= 0 }
{
absolute(value)
}

The proof report lists the native target, its effects and its contract as assumptions. The native body is not verified; the example tests it with positive, negative and zero inputs. Mark pure only when the native operation truly is pure and total on its domain: a false promise invalidates downstream conclusions. More complex native semantics can be described by ordinary checked Gale functions referenced from the contract; no compiler registry is needed to add a binding.

Three declarations cover the type side of the boundary, from most to least described:

extern struct describes a native Elixir struct whose fields Gale knows. Specs name the real %Range{} instead of term(), and Gale code can read, match, construct and update those fields on the native value. Gale emits no replacement defstruct and copies nothing:

A native range is a known Elixir struct, built through its native constructor.

mod externs.range
pub extern struct "Range" IntegerRange {
first: Integer,
last: Integer,
step: Integer
}
pub extern "Range.new" new(first: Integer, last: Integer) -> IntegerRange

Prefer native constructors when they establish invariants (Range.new over building the struct by hand). Construction requires every declared field; native defstruct defaults fill the undeclared ones; @enforce_keys still applies. At checked Gale boundaries the runtime verifies the struct module and recursively checks declared fields, allowing undeclared native ones.

extern type describes a nominal foreign value whose structure Gale does not describe: no fields, projects to term(). When a hidden value’s runtime category is known, a representation clause lets checks and proofs use it while the value stays nominal. Hidden struct fields are checked at boundaries but never inspectable:

pub extern type Worker<Message> representation(1) pid
pub extern type Token<Tag> representation(1) reference
pub extern type Box<A> representation(1) struct "Native.Box" { value: A }

extern exception describes the nominal native exception struct used in raises error unions: typed fields support construction, updates and matching. Values can be returned inside Error without raising.

extern mod "Range" range_module names a native module as a value. It imports nothing and exposes nothing. Each function still needs its own extern signature. You need it only to pass a native module through Gale code, and an implements clause can grant that value a declared behaviour capability. extern "GenServer" declares Server<...> maps Gale callback signatures onto native BEAM behaviours. The behaviours chapter has the rules.

  • Checked: every Gale caller against the declared signature; with runtime checks on, argument and result representations at boundaries, including nested fields, UTF-8, proper lists and exact records.
  • Assumed: the native implementation’s agreement with its declaration, including any pure/ensures promises. Provenance for built-in native proof models is versioned; a matching name alone creates no axiom.
  • Not claimed: function arity proves nothing about a signature; phantom/mailbox/invariant internals stay unverified; untrusted Term input must be decoded (decoding), not trusted.

Exact syntax and projection rules live in the language guide and the type-system reference.