Skip to content

Behaviours

A behaviour declares callbacks that other modules implement. Pass an implementation as a mod Behaviour<A, B> value to let the caller choose which module supplies those functions.

declares names the contract; callback declares each function of it. Optional callbacks may have a default body. When an implementation omits the callback, Gale emits the default:

A behaviour is an ordinary module. declares names the contract. Callbacks declare a shared interface. Optional callbacks may be absent or provide a real default body; overrides prove the same contract. The compiler checks every implementation against this contract.

mod behaviours.store
@moduledoc """
A behaviour is an ordinary module. `declares` names the contract.
Callbacks declare a shared interface. Optional callbacks may be absent or
provide a real default body; overrides prove the same contract.
The compiler checks every implementation against this contract.
"""
declares Store<K, V>
callback get(data: Map<K, V>, key: K) -> Option<V>
callback put(data: Map<K, V>, key: K, value: V) -> Map<K, V>
optional callback close() -> :ok { :ok }

implements goes in the implementing module’s header; the callbacks are that module’s ordinary public functions, checked against the interface:

implements is a module header. Required callbacks are ordinary public functions. Default-backed close is omitted here, so its ordinary default is emitted and callable through mod Store.

mod behaviours.memory
@moduledoc """
`implements` is a module header. Required callbacks are ordinary public
functions. Default-backed `close` is omitted here, so its ordinary default is emitted
and callable through `mod Store`.
"""
alias behaviours.store
alias gale_std.map
implements store.Store<String, Integer> as Memory
pub fn get(data: Map<String, Integer>, key: String) -> Option<Integer> {
map.get(data, key)
}
pub fn put(
data: Map<String, Integer>,
key: String,
value: Integer
) -> Map<String, Integer> {
map.put(data, key, value)
}

close is omitted above, so the declared default is emitted and callable. Implement every required callback; only callbacks with defaults may be omitted.

A mod store.Store<String, Integer> parameter is a module value that implements the behaviour. The caller picks the implementation; there is no implicit lookup and no runtime plugin scan:

A mod Store<K, V> value is a module that implements the behaviour. The caller selects the implementation; there is no implicit lookup. Passing a module that does not implement Store is a compile-time error.

mod behaviours
alias behaviours.store
alias gale_std.map
pub fn round_trip(
store: mod store.Store<String, Integer>,
key: String,
value: Integer
) -> Option<Integer> {
data = store.put(map.new(), key, value)
store.get(data, key)
}

Callbacks may declare requires/ensures, and gale verify holds every implementation to them: the callback’s requires is assumed, its ensures must be established by each implementing body.

mod behaviours.counters
declares Counter
callback step(value: Integer) -> Integer
requires { value >= 0 }
ensures { result > value }
mod behaviours.basic
alias behaviours.counters
implements counters.Counter as Basic
pub fn step(value: Integer) -> Integer { value + 1 }

Implementation clauses dispatch like ordinary functions. A multi-clause callback implementation with guards is checked clause by clause, not restricted to a single pattern.

An extern module may declare an explicit behaviour capability. The signature is trusted; Gale does not inspect the native implementation:

An extern module may expose an explicit behaviour capability. This signature is trusted: Gale does not inspect the native String module’s implementation.

mod behaviours.text
@moduledoc """
An extern module may expose an explicit behaviour capability. This signature
is trusted: Gale does not inspect the native String module's implementation.
"""
declares Text
callback length(value: String) -> Integer
pub extern mod "String" native implements behaviours.text.Text
pub fn measure(implementation: mod Text, value: String) -> Integer {
implementation.length(value)
}
pub fn native_text() -> mod Text {
native
}

OTP’s GenServer and Supervisor use the same declares/implements mechanism with declarations such as extern "Elixir.GenServer" naming the native contract. See the GenServer chapter.

  • A defaultless optional callback may be absent; abstract mod dispatch cannot call it unless a concrete implementation establishes it. A provided default emits a real function when omitted; an explicit public override replaces it and verifies the same contract; conflicting defaults from overlapping interfaces require an explicit implementation.
  • One public function can satisfy same-named callbacks in several interfaces when each conformance check succeeds independently. Combining unrelated preconditions cannot replace those separate checks.
  • Pure callbacks additionally require effect-free, terminating behavior for logical use; native framework fallback is separate from an exported function, and extern behaviours do not expand use macros.