Erlang answers through a small window

There is a small window in the side of the language. Erlang answers when we knock.

Describe the value that really crosses

Pooka can call an Erlang function through an explicit foreign module declaration:

external Numbers from erlang "erlang" {
  integer_to_binary(value: Int) -> String
}

main() {
  assert Numbers.integer_to_binary(42) == "42"
}

The declaration gives the compiler a local name, a target module and a signature. The signature has to describe the target function’s real behaviour. The compiler cannot prove a foreign implementation correct merely by reading its address.

Here the Erlang function returns a binary containing the integer’s textual representation, which is suitable for this String result.

Similar names can hide different representations

A traditional Erlang string is a list of integer character values. A Pooka string uses UTF-8 binary data. Those are not interchangeable because both happen to be called strings in conversation.

Erlang character list: [111, 119, 108]
UTF-8 binary bytes:    <<111, 119, 108>>
Pooka text:           "owl"

An FFI wrapper may need to convert values or reorganise a success/error convention. The public annotation should tell the truth after that conversion, not describe the value we wish the foreign code returned.

Keep the window narrow

There is a practical reason to keep bridges small. If collection traversal, domain decisions and error handling all move behind one foreign call, Pooka’s checker sees less of the program we wanted it to check.

The standard library uses Erlang where runtime or platform facilities are useful. Its public surface can still use Pooka classes, enums, generics and Result values.

Good tests exercise the boundary in both directions: successful values with the intended representation, and failures that return the advertised shape. A bridge tested only with 42 may become much less agreeable when somebody brings an empty binary or an invalid file path.

The window is useful because it has a frame. We should be able to point to exactly what passes through it.

— Peregrine Finch