AeronElixir

Native Elixir client for the Aeron messaging system. It bundles the Aeron C media driver, which the application starts and supervises, or connects to a driver that something else runs. It talks to the driver over the driver's shared-memory files, so an Elixir node can publish to and subscribe from the same streams as Java, C, C++ and Python Aeron clients.

Architecture

caller process ──publish/poll──► NIF (C) ───atomics──► mapped log buffers ◄── media driver
       │                                                        ▲
       └──add_publication / add_subscription──► ClientConductor ─┘  (CnC file, handshake)

• AeronElixir.NIF — the only native code in the client, a C NIF (c_src/aeron_elixir_nif.c, loaded by AeronElixir.NIF). Maps the CnC file and log buffers, provides atomic reads and writes, appends data frames (offer, offer_n, offer_list) and reads messages back with fragment reassembly (poll_collect, poll_collect_framed, peek_collect_framed, poll_count). mix compile builds it with -O3.
• AeronElixir.ClientConductor — one GenServer per client. Waits for a live driver, maps cnc.dat, sends the add and remove commands over the to-driver ring buffer, reads driver responses from the to-clients broadcast buffer, maps the log file the driver names, sends keepalives and checks the driver's heartbeat, tracks images as they arrive and leave, and invokes the image callbacks. When the driver is lost it closes every publication and image and stops. It is not on the message path.
• AeronElixir.RuntimeHandles — a public ETS table owned by each conductor holding %LogBuffer.Publisher{} and %LogBuffer.Subscriber{} handles. Every publish and poll reads its handle from this table and calls the NIF from the calling process, with no message to the conductor.
• AeronElixir.BatchPublisher — a process that owns one publication and sends everything queued in its mailbox as one native call each time it runs.
• AeronElixir.MediaDriver — runs a C media driver as a Port owned by an Elixir process: the bundled one by default, or any aeronmd binary.
• AeronElixir.DriverConfig — decides which driver the application uses: the bundled driver, started under the application's supervisor, or a driver named by AERON_DIR or config :aeron_elixir, :aeron_dir.
• Bundled driver — mix compile (Mix.Tasks.Compile.AeronNative, which also builds the NIF) builds the Aeron 1.51.0 C client and driver into priv/bin/aeronmd. The first build downloads the 1.51.0 release archive from GitHub, checks its pinned SHA-512 and unpacks the C sources into _build/aeron-1.51.0; later builds reuse them. Set AERON_SOURCE_DIR to an unpacked Aeron 1.51.0 tree to build without network access.
• AeronElixir.Resources.* — Ash resources (Client, Publication, Subscription, Image, Counter) backed by ETS. Lifecycle (connect, add, close) goes through Ash actions; the action changes call the conductor.
• AeronElixir.Protocol.* and AeronElixir.ChannelUri — pure Elixir encoders and decoders for the control protocol, the 32-byte data frame header and channel URIs, byte-matched to the Aeron Java flyweights, plus a validated URI builder.

Public API

All functions live in AeronElixir unless a module is named. publication means a %Resources.Publication{} record or a %LogBuffer.Publisher{} handle; subscription a %Resources.Subscription{} record; image a %LogBuffer.Subscriber{} handle.

Client and lifecycle:

Publishing:

Payloads are binaries or iodata; iodata segments are written straight into the frame without flattening. Messages longer than max_payload_length are fragmented on publish and reassembled on poll.

Polling:

%Protocol.Frame{} carries frame_length, version, flags, type, term_offset, session_id, stream_id, term_id, reserved_value, initial_term_id and position (the stream position after this frame).

Channels, idling, driver:

Counters: add_counter/4, increment_counter/2, counter_value/1.

Publications are also exposed as Ash actions on the resources (AeronElixir.Resources.Publication.publish, Subscription.poll, Image.poll) for callers that work through the Ash domain.

Hot-path contract

• publish/2, try_publish/2, publish_list/2 and publish_n/3 are safe to call from many processes on the same publication. Term space is reserved with an atomic add on the term tail, and term rotation is guarded by a CAS, matching Aeron's concurrent Publication.
• Only one process may poll a given subscription or image at a time. The subscriber position counter is single-reader.
• Every payload returned by one poll_batch/2, poll_image_batch/2, poll/3 or controlled_poll/3 call is a sub-binary of a single allocation for that call, except that a poll_batch/2 or poll_image_batch/2 call returning one payload of 64 bytes or less returns it as a binary of its own. Holding one payload of a batch keeps the whole batch alive; :binary.copy/1 any payload kept beyond the call.
• A message whose fragments are not all published yet is left for a later poll.
• Nothing on the message path sends a message to the conductor or any other process.
• Once a publication or image is closed, by close/1 or because its client lost the driver, publishing returns {:error, :closed} and polling reads nothing. A handle keeps its mappings alive for as long as it is reachable, so using a closed handle is always safe.

Requirements

• Elixir 1.19+ / OTP 28
• A C compiler: cc, or the one CC names. On macOS that is the Xcode Command Line Tools (xcode-select --install); on Linux, gcc or clang. No CMake or separately installed media driver is required.

Build

mix deps.get
mix compile

mix compile builds the NIF into priv/lib/aeron_elixir_nif.so and the media driver into priv/bin/aeronmd, each only when one of its sources has changed.

Usage

The application starts the bundled media driver and supervises it, so a client needs no configuration. From an application or iex -S mix:

{:ok, client} = AeronElixir.start_link()

channel = AeronElixir.ChannelUri.ipc(alias: "orders", term_length: 16_777_216)
{:ok, publication} = AeronElixir.add_publication(client, channel, 1001)
{:ok, subscription} = AeronElixir.add_subscription(client, channel, 1001)
:ok = AeronElixir.await_connected(publication)

{:ok, _position} = AeronElixir.publish(publication, ["order:", "42"])

handler = fn payload, header ->
  IO.inspect({AeronElixir.Header.session_id(header), AeronElixir.Header.position(header), payload})
end

1 = AeronElixir.poll(subscription, 10, handler)

{:ok, 3} = AeronElixir.publish_list(publication, ["a", "b", "c"])
{:ok, 3, ["a", "b", "c"]} = AeronElixir.poll_batch(subscription, 64)

AeronElixir.close(publication)
AeronElixir.close(subscription)
AeronElixir.close(AeronElixir.client(client))

For the lowest per-message cost, fetch the handles once and use them from the processes that own the work:

{:ok, handle} = AeronElixir.publication_handle(publication)
{:ok, images} = AeronElixir.subscription_handles(subscription)

{:ok, _position} = AeronElixir.publish(handle, "direct")
{:ok, 1, ["direct"]} = AeronElixir.poll_batch(hd(images), 64)

To let many processes publish without each paying a native call, route them through a BatchPublisher:

{:ok, batcher} = AeronElixir.BatchPublisher.start_link(publication: publication)
:ok = AeronElixir.BatchPublisher.publish(batcher, "fire and forget")
:ok = AeronElixir.BatchPublisher.flush(batcher)

Media driver

Which driver the application uses, in order of precedence:

config :aeron_elixir, driver: :embedded with a directory makes this application start and own the driver at a shared location, for other applications on the host to connect to. config :aeron_elixir, binary: path launches another aeronmd instead of the bundled one.

The private directory is $XDG_RUNTIME_DIR/aeron_elixir/os-<pid>, or under /dev/shm or the system temp directory when that is unset: memory-backed, per-user runtime storage. The driver recreates its files on every start and deletes them when it stops; directories left by a VM that died are swept on the next start. If the VM dies without stopping the driver, the bundled driver notices and shuts itself down.

mix aeron.driver prints the mode, the directory and the binary with its version, so another program can run the same binary or connect to the same directory.

Extra drivers, for example one per tenant, are ordinary children:

{AeronElixir.MediaDriver, aeron_dir: "/run/aeron/tenant_a", name: MyApp.TenantADriver}

Losing the driver

The client follows the Aeron client contract. Every keepalive interval the conductor reads the driver's heartbeat. When the driver has shut down, has not heartbeated for driver_timeout_ms (default 5000, a start_link/1 option), or reports that this client timed out, the conductor closes every publication and image (publishing returns {:error, :closed}, polling reads nothing, unavailable_image handlers run) and stops with {:shutdown, :driver_shutdown}, {:shutdown, :driver_timeout} or {:shutdown, :client_timeout}. The client is never reconnected in place: a restarted driver has new buffers and positions, so messages in flight are gone, and recreating a publication is a new session.

The process started by start_link/1 exits with that reason. Supervise it, and put the processes that own publications and subscriptions after it in a :rest_for_one supervisor, so a lost driver restarts them in order and they add their publications and subscriptions again; connecting waits for the driver:

children = [
  {AeronElixir, name: MyApp.Aeron},
  MyApp.OrderPublisher
]

Supervisor.start_link(children, strategy: :rest_for_one)

The embedded driver is supervised the same way: if it exits, the application restarts it and then its clients.

Examples

examples/ holds runnable scripts. Each uses the driver the application selects, so they run with no setup; 10_lifecycle.exs also starts and stops a second driver of its own.

mix run examples/01_ipc_producer_consumer.exs
mix run examples/10_lifecycle.exs

examples/README.md maps each script and each API call to its pyaeron equivalent.

Coverage against upstream samples

The reference examples for any Aeron client are the samples in the Aeron repository (aeron-samples/src/main/java/io/aeron/samples and aeron-samples/src/main/c). What each needs, and whether this client provides it:

Counting the rows: 10 expressible, 3 partial, 6 not.

Testing

mix test

Tags: :system (uses the application's driver: the bundled one, or the one AERON_DIR names), :interop, :protocol. mix quality runs the formatter, Credo (strict) and Dialyzer.

Benchmarks

Four harnesses, all over aeron:ipc against one C media driver that every client shares, each writing its results under bench/results/. Start that driver first, for example AERON_DIR=/tmp/ae_drv ../aeron/build/binaries/aeronmd_s; with AERON_DIR set, the Elixir clients connect to it instead of starting the bundled driver.

• bench/run.exs — single process: latency (offer → poll round trip, one message at a time) and throughput (batches of 1000 with drain) per client and payload size; summary.{csv,json,html}.
• bench/run_multiproc.exs — N workers per client, each with a private publication and subscription pair; multiproc.md.
• bench/run_rpc.exs — request/response round trip between two processes, 32 bytes, one request in flight; rpc.md.
• bench/harness/run.exs — market data: a C price publisher (bench/harness/price_server.c) in its own process, each client consuming its ticks in turn; harness.md.

AERON_DIR=/tmp/ae_drv mix run bench/run.exs
AERON_DIR=/tmp/ae_drv mix run bench/run.exs clients=elixir_raw,python sizes=32,256 time=5
AERON_DIR=/tmp/ae_drv mix run bench/run_multiproc.exs workers=1,2,4,8,12 sizes=256,32
AERON_DIR=/tmp/ae_drv mix run bench/run_rpc.exs
AERON_DIR=/tmp/ae_drv mix run bench/harness/run.exs

merge=true keeps the stored results of clients a run does not include, and clients= with no clients re-renders the stored results without running anything.

Per message, every Aeron client does the same work in every harness: stamp a 28-byte tick (instrument id, bid, ask, sequence) into the payload, offer it, and on receive decode the four fields into a running sum. Every client is a program in this repository rather than an upstream sample.

Every message differs. Each client builds the same pool of 4096 payloads before any timing starts, cut from one splitmix64 byte stream (seed 0x5EEDAE20, outputs written little-endian), and message i is pool entry i mod 4096 with its tick stamped over the first 28 bytes. The C, C++, Java, Python, Elixir, Go, .NET and Rust implementations build byte-identical pools (bench/c/payload_pool.h, bench/cpp/payload_pool.hpp, bench/java/PayloadPool.java, bench/python/payload_pool.py, AeronElixir.Bench.Shared.payload_pool/1, benchkit.NewPool, bench/dotnet/BenchKit/Kit.cs, bench/rust/src/lib.rs).

Other variants run when named in clients=: elixir in the single-process harness (the record functions publish/2 and poll/3), elixir_list (publish_list/2, 1000 messages per call), elixir_invm (request/response with both sides in one VM), elixir_public (market data through poll/3) and beam (BEAM send/receive, no Aeron).

Prerequisites per client: c/cpp need ../aeron built with CMake (bench/c and bench/cpp link against ../aeron/build/lib; bench/c also builds the market-data publisher); java needs aeron-all-1.49.3.jar in ~/.m2; python needs bench/python/.venv with pyaeron installed (uv venv --python 3.14 bench/python/.venv && uv pip install --python bench/python/.venv/bin/python pyaeron); go needs the binaries built in bench/go (cd bench/go && go build -o build/ ./cmd/...), with Go 1.27 pinned for that directory in bench/go/mise.toml and aergo pinned in bench/go/go.mod. dotnet needs the .NET 10 SDK (Homebrew dotnet, or mise use dotnet@10 in bench/dotnet; bench/dotnet/global.json pins the SDK major) and the four programs published into bench/dotnet/build: cd bench/dotnet && for p in Bench BenchMultiproc Rpc Consumer; do dotnet publish $p/$p.csproj -c Release -o build; done. The runners start them with dotnet <Program>.dll, and NuGet fetches Aeron.Client 1.52.2 on the first build. rust needs Rust 1.91 (mise) and CMake, because rusteron-client compiles the Aeron C client: cd bench/rust && cargo build --release builds the four programs into bench/rust/target/release.

aergo has no conductor thread: the caller runs its conductor with DoWork(). The Go programs call it while waiting for the first message, which is when the image is discovered, and once every 1024 operations for keepalives. Apart from that, each Go program does exactly what the C program for the same harness does.

All results below come from one run on an Apple M3 Max (12 performance and 4 efficiency cores), macOS 27, OTP 28 and Elixir 1.19.5, with one C media driver on default threading shared by every cell and no CPU pinning. The machine is a desktop with other applications running, and multi-worker results in particular vary between runs by tens of percent. The rust rows were measured in a later session than the others.

Single process

Median round trip, µs (offer then poll on one thread):

C, C++, Java, .NET and Rust share the lowest median, 0.041–0.042 µs; Go follows at 0.083 µs and aeron_elixir at 0.125 µs, ahead of Python's 0.292 µs. Every client stamps a fresh tick into each message inside the timed window. Full percentiles for every client are in the round-trip section below.

Throughput, million messages/s:

Varied payloads

Every message in every harness differs (see above). Measured on its own, by building the previous identical-payload C and C++ programs from source and alternating them with the current ones at 32 B: the varied pool costs the C client about 11% of its throughput (112.2 M to 99.7 M messages/s, and 36.7 M to 32.7 M at 1024 B), while the C++ client is unchanged (61.2 M against 61.0 M). In the multi-worker harness at 256 B each worker reads its own 1 MB pool, so twelve workers stream 12 MB of distinct payloads.

Multi-worker

Aggregate million messages/s for N workers, each with its own publication and subscription pair. Elixir workers are BEAM processes in one VM sharing one client; Java and .NET threads share one client; C and C++ use one client per thread, as does Rust; Go uses one aergo client per goroutine; Python uses one OS process and one client per worker.

256 B:

32 B:

aeron_elixir scales furthest from one worker to twelve: 8.96x at 256 B and 9.56x at 32 B, against 4.4x for .NET and 2.5x for C at 256 B. At 256 B C peaks at four workers and C++, Java and Rust at eight, while .NET, Go, Elixir and Python keep rising to twelve. Absolute throughput still favours the native clients: at twelve workers C carries 1.7 times aeron_elixir at 256 B and 5.1 times at 32 B. Rust and C drive the same Aeron C client, so the gap between them here (Rust 660 M messages/s against C's 500 M at 32 B and twelve workers) is the run-to-run variance described above, not a difference between the clients.

NIF call cost

A NIF call costs the same whatever else the node is doing. bench/elixir/nif_ceiling.exs measures a trivial C add/2 NIF, aeron_elixir's own read_int64/1 and a pure BIF across a rising number of concurrently calling processes. At twelve callers the C NIF costs 11.6 ns, read_int64/1 14.9 ns and the BIF 12.0 ns. The figures stay between 10 and 17 ns from one to twenty callers, and twelve callers together make over 1,000 million add/2 calls per second. :crypto.hash/2 rises from 121 ns to 2,825 ns over the same caller counts and its aggregate throughput falls; that is contention inside crypto and says nothing about the NIF call path.

Request/response round trip

32-byte messages, one request in flight, 100,000 warmup round trips then 1,000,000 measured. Both sides encode and decode the tick: the pinger stamps it into the next pool entry, offers it, spin-polls for the echo and decodes the echo's four fields; the ponger decodes every request before echoing it back. Both print their accumulated sum so the decode cannot be optimized away. Each pair is two OS processes.

Round trips/s is the measured round trips divided by the wall-clock time of the timed loop. aeron_elixir's median, 0.250 µs, is twice the C, C++ and Rust clients' 0.125 µs and 1.5 times .NET's and Java's; its p99.9 is the widest of the Aeron clients.

Three differences in the responders are properties of the clients rather than the harness. Python copies the payload with tobytes() before echoing, because a pyaeron BufferView is only valid during its callback. aergo copies each payload into a reused buffer before calling the handler. Elixir materializes the payload as a BEAM binary, because a BEAM binary cannot alias mutable shared memory. C, C++, Java, .NET and Rust echo the log buffer directly.

N concurrent pairs, aggregate round trips/s and the median pair's p50. Every pinger finishes its warmup and then waits for one wall-clock start time that the runner sets, so the timed loops of all N pairs run at the same time; the aggregate is the total round trips of all pairs divided by the time from the first pair's start to the last pair's finish. In this run every pinger began within 14 ms of the start time.

Every client peaks at four pairs. Twelve pairs are 24 busy-spinning processes on 16 cores, so pairs take turns on a core and every aggregate falls. At twelve pairs C carries the highest aggregate, 14.49 M round trips per second, followed by C++ (12.66 M), Rust (11.16 M) and .NET (10.82 M); aeron_elixir carries 5.80 M, and its median pair's p50 doubles from 0.250 µs to 0.500 µs.

Market data

bench/harness/run.exs runs a synthetic price publisher, a C program on the Aeron C client, as its own OS process and has each client consume its 64-byte ticks in turn, first with the publisher flat out, then at fixed rates. Each cell is run three times and the median run is shown: the median consume rate flat out, the median p99 at a fixed rate. Full method and commentary are in bench/results/harness.md.

Rate steps, p50 / p99 µs:

Flat out, a consumer that back-pressures the publisher is reading as fast as it can, so its consume rate is its own maximum. Rust reads 33.4 M ticks/s and C 32.1 M; C back-pressured the publisher for under a millisecond, so it kept pace with the publisher itself. .NET reads 27.9 M, Java 26.1 M, Go 24.9 M, aeron_elixir 9.5 M and Python 2.7 M. Saturation latencies are queue depth, not transport cost.

Every side timestamps with CLOCK_REALTIME, which on macOS advances in 1 µs steps, so the fixed-rate latencies are whole microseconds and a p50 of 0.05 µs means the tick was read within the microsecond it was stamped. At that resolution, C, .NET and Rust read 99% of ticks within the microsecond they were stamped at every rate, aeron_elixir within 2–3 µs and Go within 11–12 µs; Python matches the C-based clients up to 1 M/s and needs 4 µs at 2 M/s. java reports 0.55 µs where the others report 0.05 µs because its consumer adds half a clock step to remove truncation bias.

Web page

docs/ holds the project's web page: the overview, the benchmark results with charts for every suite and option, and a page per example. elixir site/build.exs builds it from this checkout, reading bench/results, README.md and examples/. Each page is a single HTML file with its styles and scripts inline. GitHub Pages serves it from the main branch and the /docs folder, so after a benchmark run, rebuild the page and commit it with the new results. Example pages link to their source on GitHub when the origin remote is a GitHub repository or AERON_ELIXIR_REPO=owner/name is set.

Limits and roadmap

• aeron:ipc and aeron:udp both carry messages end to end, covered by test/aeron_elixir/udp_test.exs and examples/12_udp.exs. UDP is verified over loopback only; a second host would additionally exercise a 1500-byte MTU, packet loss and multicast. Spy subscriptions and response channels are not supported.
• No multi-destination cast or multi-destination subscription: the ADD_DESTINATION and REMOVE_DESTINATION commands are not sent.
• No try_claim; iodata publishing covers writing without an intermediate copy.
• No SBE codec generation. Payloads are opaque binaries.
• Driver observability is limited to single counters: no reader over all driver counters with their labels, no error log decoding, no loss report.
• Archive, Cluster, authentication and authorisation are not implemented.
• Planned: verify the UDP path, destinations for multi-destination cast, generate SBE codecs from a schema, a counters and error-log reader, and a relay client example for an Aeron Cluster egress stream.

License

Apache License 2.0; see LICENSE. The Aeron sources the bundled driver is built from are Apache 2.0; NOTICE credits them.