Public repository: github.com/lukaszsamson/bendler
Call Bend code from Elixir, the way Rustler calls Rust and Zigler calls Zig. A Bend file becomes an Elixir module: every exportable def is a function, and the Bend program runs either as a port executable beside the VM or as a NIF inside it.
The supported surface is the CPU port binding, frozen for 0.1.x in API.md. The NIF and GPU lanes are opt-in experiments outside that promise. DESIGN.md explains why the program serves requests through foreign effects, and VALIDATION.md describes what is checked.
| Component | Status |
|---|---|
| Bend | 2.0.39 only |
| OTP | 28 baseline |
| macOS | arm64, covered by macOS 15 CI (Metal API baseline) |
| Linux | x86_64 / Ubuntu 24.04, covered by CI |
| Windows | Not supported |
# bend/fib.bend
import Base
def fib(n: Nat, a: U32, +b: U32) -> U32:
match n:
case 0n:
a
case 1n+p:
fib(p, b, (a + b : U32))
def pow2(+n: Nat) -> U32:
match n:
case 0n:
1
case 1n+p:
a b = pow2(p) pow2(p) # parallel calls on the configured worker pool
(a + b : U32)defmodule Fib do
use Bendler, otp_app: :my_app, source: "bend/fib.bend", timeout: 5_000
end
# the default backend is a port: start it under your supervisor
children = [Fib]
Supervisor.start_link(children, strategy: :one_for_one)
Fib.fib(30, 0, 1) #=> 832040
Fib.pow2(20) #=> 1048576bend emits C and clang builds it. Both must be installed (bend is
looked up on PATH, then at ~/.bend/bin/bend; config :bendler, bend: path overrides). Only Bend 2.0.39 is accepted, because the C side depends
on runtime internals; config :bendler, allow_any_bend: true lifts the gate.
CI pins LLVM clang 21.1.8, OTP 28.1 and Elixir 1.20.3. When using upstream
LLVM on macOS, set SDKROOT to xcrun --sdk macosx --show-sdk-path; the CI
installer also selects its bundled Mach-O linker to avoid mixing LLVM's
C++ runtime with Apple's linker.
With the Mix compiler listed, the build runs after Elixir compilation:
def project, do: [compilers: Mix.compilers() ++ [:bendler], ...]mix compile.bendler --force rebuilds, mix bendler.clean removes the
artifacts. Without the compiler, use Bendler builds while the module
compiles. Either way the artifact lands in priv/bendler/ and is rebuilt
only when its fingerprint changes: the source and the files it imports, the
generated shim and C, and the toolchain (bend and its Base, clang, the
target, OTP). A release ships the artifact and does not need bend.
| option | meaning |
|---|---|
otp_app |
the application whose priv/bendler/ receives the artifact |
source |
the Bend file, relative to the project root |
backend |
:port (default) or :nif (experimental, opt-in) |
threads |
CPU threads for the Bend runtime (default: schedulers online) |
exports |
the defs to export (default: every exportable def) |
timeout |
milliseconds a call may wait (default :infinity); port: the owner closes the port and stops, a supervisor restarts it; NIF: the caller gives up, the reply is discarded when it comes |
max_queue |
port: callers allowed to wait behind the one in flight (default 8) |
max_waiting |
NIF: total staged, queued and running calls (default 4); callers wait in Elixir |
gpu |
port: where ! calls run: :off (default, the CPU pool), :on, or a heap cap like "4GB"; a program with ! is built with its GPU lane and ships <name>.gpu beside the executable |
The port module has start_link/1 and child_spec/1; options given there
override the module's. Put it under a supervisor before calling it.
| Bend | Elixir |
|---|---|
U32 |
integer in 0..2^32-1 |
Nat |
integer in 0..2^48-1 (the runtime's immediate range) |
String |
binary (UTF-8; invalid bytes become U+FFFD) |
Bool |
boolean |
Unit |
:unit |
List<T> (also +List<T>, List<&2, T>) |
list |
B.Bytes (the prelude's) |
binary |
A & B, A & B & C |
{a, b}, {a, b, c} (2–16 fields) |
Maybe<T> |
:none or {:some, value} |
Result<E, T> |
{:error, error} or {:ok, value} |
F32 |
float, rounded to single precision; :nan, :infinity, :neg_infinity for the values the BEAM has no float for |
Char |
integer code point (0..0x10FFFF, no surrogates) |
Map<V> (also Map<&2, V>), a whole parameter or result |
map with valid UTF-8 binary keys |
type T is Data: of the same file |
{:ctor, field, ...} per constructor, :ctor without fields |
IO(T) result, with ~emit: E -> IO(Bool) |
the value, plus a _stream yielding {:event, e} then {:done, value} |
These types compose recursively, including bytes inside tuples and variants;
only Map has to be a whole parameter or result, because it crosses as a
list of pairs that Base's Map.from_list and Map.to_list convert on the
Bend side. A user datatype crosses as the prelude's Dyn tree, converted
by defs the build generates into the shim, so type Shape is Data: with
Circle{r: U32} and Dot{} takes {:circle, 3} and :dot; recursive
types (a tree, a linked list) work, with the rules in Bendler.Sig. See
type contracts and the accepted contract subset for nesting limits, parentheses, the float
policy, the datatype rules and the distinction between Result failures
(data) and transport exceptions.
Bytes comes from a small Bend prelude, bendler.bend, that the build
writes next to any source using it; import it as import ./bendler.bend as B. A Bytes{len, buf} holds one byte per slot of an Array<U32>
buffer, so a binary crosses as one block instead of a list cell per byte
(30x faster for 64 KB in the Murmur3 demo). B.Bytes.to_list/1,
B.Bytes.from_list/1, B.Bytes.from_list_n/2 (a known length bound) and
B.Bytes.at/2 are the helpers.
A def is exported when all its parameters and its result are of these types,
or when its result is IO(T) of one of them (see "Events out of Bend").
Except for the recognized emit and ask callbacks below, erased (-) and
template (~) parameters, closures, arrays and
unsupported types keep a def out (it is reported at debug level). main is
never exported: the shim supplies its own. Reusable (+) parameters are
honoured.
A def that answers IO(T) may take a typed emitter, and then one call
can hand the BEAM a stream of values while it is still running:
def fly(~emit: B.Bytes -> IO(Bool), scene: Scene, w: U32, h: U32,
frames: U32, cx: F32, cz: F32) -> IO(U32):
... # render a frame, emit it, stop early on FalseRaytrace.fly_stream(scene, 320, 240, 48, 0.0, 5.0)
|> Stream.each(fn
{:event, rgb} -> write_frame(rgb) # each frame as Bend finishes it
{:done, n} -> IO.puts("#{n} frames")
end)
|> Stream.run()The emitter is not a wire argument: the shim supplies a lambda over a
foreign effect, Bendler.emit, which encodes the value with the
same codec a reply uses, writes it as an EVENT frame and then parks on the
host's acknowledgement. At most one event is outstanding, the
worker cannot run ahead of the consumer, and an acknowledgement of False
is a typed, cooperative "stop" that the def sees as an ordinary value.
Every export with an emitter gets two functions: fun(...), which refuses
the events at once (each emit answers False, asking the def to stop),
and fun_stream(...), a lazy Enumerable of
{:event, value} ending in {:done, result}. Demand drives the
acknowledgements: the one for an event goes out when the next is asked
for, so a paused consumer holds one event and the worker waits. Halting
early (Enum.take/2), an exception in the consumer, and the consumer's
death request cancellation. The port becomes reusable after the def returns;
a finite in-flight deadline terminates a worker that ignores cancellation.
Events are type-checked like
replies. Write the emitter with ~ (Bend's template marker) whenever the
def emits more than once: a Bend function type is Type-kinded, so a
closure binder can never be reusable.
Events work on both backends. Port uses EVENT frames and a one-byte
acknowledgement; the experimental NIF uses sequence-tagged
{:bendler_event, ref, seq, bin} messages with sequence-checked
acknowledgements. Early NIF stream termination returns after cancelling
delivery; the native admission slot stays occupied until the def
cooperatively finishes.
The particle tick demo runs the same simulation on port and NIF, writes SVG trajectories, and measures scalar-event overhead separately from simulation and payload costs.
The raytracer demo's fly is the worked
example: one call renders a whole camera turn and each frame arrives in
Elixir as it finishes, assembled into an animated PNG while the render is
still running.
A parameter named ask, written ~ask: Request -> IO(Response), is the
other direction: the Bend def pulls host-owned input while its own state
stays inside Bend. The generated Elixir function takes a final unary
handler argument.
CsvAskPort.aggregate(16_384, 65_536, 1_000_000, fn {offset, count} ->
case :file.pread(io_device, offset, count) do
{:ok, bytes} -> {:ok, {:some, bytes}}
:eof -> {:ok, :none}
{:error, reason} -> {:error, inspect(reason)}
end
end)One ASK is outstanding at a time, and an export has one callback channel:
ask or emit, not both. The handler runs in a fresh linked and monitored
process with a fixed five-second deadline, inside the call's total
deadline. A handler failure, an invalid response or a handler timeout
raises Bendler.Error with reason :callback; direct same-worker reentry
from the handler raises :reentrant. A typed Result.Fail is ordinary
data. See the ask-driven CSV aggregation demo.
Arguments are checked on the Elixir side and raise ArgumentError. A call
returns the value or raises Bendler.Error, whose reason is :busy
(admission limit hit), :timeout, :exited (the port died; a supervisor
restarts it), :dead (the NIF runtime is frozen), :refused (the program
rejected the frame), :nomem (a native transport allocation failed),
:callback, :reentrant or :build.
Elixir Bend program (one C file from `bend -o x.c`)
────── ──────────────────────────────────────────
Fib.fib(30, 0, 1)
│ Bendler.Codec: <<idx::32, args>>
▼
NIF admission → dirty validation ─▶ Bendler.fn() (foreign effect: waits for a frame)
or Port ({:packet, 4}) ────────▶ Bendler.arg(T) (foreign effect: decodes one argument)
M.fib(n, a, b) (the user's Bend def)
◀── event frame/message ◀──────── Bendler.emit(T, x) (writes, then waits
── acknowledgement ───────────▶ for the host's answer as a Bool)
◀──────────── reply frame ◀──────── Bendler.reply(T, x) (foreign effect: encodes the result)
Bendler generates a shim: a Bend file that imports yours, declares the
foreign effects (Bendler.fn, Bendler.arg, Bendler.reply, plus
Bendler.emit or Bendler.ask when an export needs one) and a main that
loops: read a function index, pull each argument, call the def, reply.
Bend's own compiler emits the C; the effects are ordinary Bend foreign C
files (priv/c/), spliced into that C by the compiler. The same shim serves
both backends, with transport-specific delivery helpers and NIF glue:
- port: length-prefixed frames on stdin/stdout, the reads parked on
Bend's event loop (
io_wait_on). Reply writes can block on pipe backpressure. - NIF: the emitted C is patched (
main→bend_main, the runtime's signal handlers dropped,_exit→bendler_die) and linked as a shared library with a smallerl_nifentry table. Checked initialization pins the library for the VM lifetime, then runsbend_mainwith+RTS --threads N --gpu off -RTS. Normal-scheduler admission precedes dirty validation and copying; native completion sends a message. Waiting uses an ordinary Elixirreceive.
The codec constructs Base values and the controlled Bytes and Dyn types
from Bendler's prelude with runtime helpers. Generated Bend converters handle
user constructors, so C does not depend on their arbitrary layouts.
- One request at a time per module. The shim's loop is sequential;
admission is bounded (
max_queue,max_waiting) and the rest are told:busyat once. Pure forks inside a call use the configured worker pool. An event belongs to the one request in flight, and its acknowledgement round trip adds a transport round trip. Batch fine-grained events when that cost dominates useful work; measure the trade-off for your workload. - Event cancellation is cooperative on both backends.
Falseis a value the Bend def must act on; a def that ignores it keeps being answeredFalseuntil it returns. A finite Port deadline can terminate the whole worker. Ask callbacks instead require a typed response; abandonment replaces the Port worker or freezes the NIF module. - Batch small calls. Encoding and hand-off costs can dominate short kernels. The Levenshtein benchmark compares individual and batched calls against an Elixir reference.
- In-flight Port deadlines stop the worker. A queued request can expire without stopping it. For an in-flight timeout, the owner closes the port and stops; a separate POSIX launcher sends TERM to the worker process group, then KILL after 200 ms, and reaps the child. Owner death is covered too. This discards the whole worker, not just one computation.
- NIF cancellation of running work does not exist. A deadline, a halted stream or caller death abandons the request: the computation runs to completion and its reply is dropped. Queued work can be removed; running work keeps its admission slot until the def returns.
- A Bend runtime error freezes that module's NIF runtime: the runtime's
_exitis routed tobendler_die, so later calls raiseBendler.Errorwith reason:deadinstead of taking the VM down. The frozen runtime keeps its threads and memory until the VM exits. A crash in the C runtime proper (a segfault) still kills the VM, as with any NIF. An abandoned or failed NIF ask freezes its module the same way, because there is no safe native request unwind. The port backend has the process boundary instead: a runtime error exits the worker (1), a memory fault ends it by its signal (reported as 128 + the signal, 139 for SIGSEGV), a protocol error exits 65, a transport error 74, and a supervisor restarts it. - NIF admission precedes dirty scheduling.
max_waitingcounts staged, queued and running requests. - NIF runtimes are pinned until VM exit. A retained callback-bearing resource prevents code purge from unloading code beneath live threads. It deliberately retains the library, threads and memory; this is not graceful runtime unload. Upgrade is refused. Replacing a loaded artifact or repeatedly reloading modules is unsupported.
- The NIF deadline is absolute. Ordinary calls and streams start it before encoding; ask calls currently start it after initial encoding. Scheduler queueing and validation consume the same budget, but scheduling can still delay delivery of the timeout. This is not a hard real-time guarantee.
- The emitted C is patched by regex. The build asserts each patch
matched exactly as expected and that no
sigaction,signal,_exitorabortcall survives. These checks and the version gate guard known assumptions; they cannot prove compatibility with an arbitrary Bend release. - A malformed request never reaches a def. Every request is validated
against the export's type spec, without allocating, before it is handed
to the runtime: the NIF does deep validation on a dirty CPU scheduler and answers
:refused; the port worker answers an error frame and goes on. Frames are capped at 64 MiB (-DBENDLER_MAX_FRAME), list items per request at 16M (-DBENDLER_MAX_ITEMS), type-spec nesting at 32 and value nesting at 2048. Decoded allocation admission defaults to 64 MiB; this is not an OS RSS cap. Replies are checked against the declared return type too. - Artifacts use
priv/bendler/<target>/<env>/despite Mix's shared priv symlink. Build and clean share a filesystem lock; abandoned locks require manual recovery after verifying that the owning build has died. - Each NIF module reserves 8 GiB of virtual address space (the runtime's
heap arena,
MAP_NORESERVE) plus 2 GiB of virtual stack per worker thread. Natvalues are limited to2^48-1; the codec rejects larger integers.- The GPU lane (
f!(x)) works through a port (Metal on macOS, CUDA on Linux when installed) and is off unlessgpu:says otherwise; a NIF runs!on the CPU pool and refuses the option. Whether it is faster is the kernel's shape, not a flag: the ray tracer's scene-as-list renderer is about 50x slower per pixel on the device. Per-bang work must stay moderate, because macOS aborts a long Metal command buffer and the worker exits 1. A toolkit without a visible device produces a CPU-capable executable with no.gpusidecar. Rebuild withmix compile.bendler --forceon the GPU host before enabling that lane. Hosted CI does not promise GPU coverage. - The C side depends on runtime internals (
io_eff,io_str,ctr_take, ...). Bend promises no ABI: rebuild on every Bend update (the build hash includes thebend version).
lib/bendler.ex use Bendler: builds at compile time, defines the functions
lib/bendler/sig.ex parses def signatures, decides what is exportable
lib/bendler/gen.ex writes the shim; patches the emitted C for the BEAM
lib/bendler/build.ex runs bend and clang, caches by input hash
lib/bendler/codec.ex the frame codec
lib/bendler/port.ex the port owner: bounded queue, deadline, events, exit codes
lib/mix/tasks/ mix compile.bendler and mix bendler.clean
priv/c/ the foreign effects and the two transports
priv/bend/bendler.bend the prelude (Bytes), copied next to sources that use it
bend/fib.bend the example module
test/support/ Bendler.Examples.FibNif and FibPort, and the crash and admission fixtures
demos/<name>/ a real port each (Bend source, port module, reference, tests, bench)
test/ the suite (mix test)
docs/API.md the stable 0.1.x surface
docs/TYPES.md the type and value mapping
docs/CONTRACTS.md operational semantics, budgets, errors, telemetry
docs/DESIGN.md why the design is what it is
docs/NIF.md the experimental NIF backend
docs/VALIDATION.md what is checked, and what is not
docs/ROADMAP.md what is waiting on Bend upstream, and what is deferred
| Demo | What it shows |
|---|---|
| levenshtein (no README) | batching independent CPU work across the boundary |
| murmur3 | packed B.Bytes against a list of bytes: 0.28 ms vs 8.5 ms for 64 KB |
| thumbhash | a real numeric/image kernel, and F32 against doubles |
| mandelbrot | CPU parallelism against scalar Elixir and Nx/EXLA, with thread scaling |
| sorting | when the work should stay in Elixir: transport can exceed Enum.sort |
| csv | tuples, Maybe and Result; eager and lazy streaming parsing against NimbleCSV |
| csv ask | a typed ask callback pulling host-owned input, aggregating inside Bend |
| raytrace | user datatypes in, Bytes out, parallel tiles, typed events, the GPU lane |
| particles | event delivery on port against the experimental NIF |