pll-elixir

The Rate, Pacer and complete Follower are implemented in this source checkout. Version 0.1.0.

This library helps audio/video, sensor, packet and device-buffer applications pace units on their own timeline or learn the relationship to another clock. A rational Pacer issues numbered slots without accumulated rounding drift. A type-II, second-order phase-locked Follower estimates remote-clock phase and frequency, filters delivery jitter, and maps ticks to local nanoseconds. They work separately or together: follower trim can steer a pacer.

Provenance, parity and non-goals

Source: Go github.com/version2beta/pll, revision 971282632129110794c9d6edd22026e9de2359be. Basis: full SPEC.md and README.md, public rate.go, pacer.go, span.go, follower.go, errors/status/package comments, and rate/pacer/follower examples, boundary and differential-model tests. The original is provenance, not a runtime dependency.

Functional equivalence means exact pacer results and equivalent follower equations, state transitions, error categories and atomic failures on the shared domain. It does not require Go ABI, duration formatting, writable span fields, iterator protocol, zero-value controller structs, sentinel-error matching, internal layouts, Go-specific fast paths, or mutating Go-style receivers. There is no transplanted claim about Go benchmark times, zero allocations, race-detector or simulator results, or real-time scheduler performance.

This is a library, not a sleeping rate limiter, token bucket, scheduler, PTP/NTP/system-clock servo, counter-unwrapper, device driver, payload queue or transport. The checkout includes a throughput harness and a bounded local pacing demonstration, documented below. These are separate from the pure library; full Go command parity and a simulator product are not included. No GenServer, Agent, Task, supervision tree or application-start callback is needed to use the core. Caller-owned OTP integration is an adapter concern.

Requirements and installation

Requires Elixir >=1.15 and Erlang/OTP >=26, binary64 floats and arbitrary-precision integers. No runtime or test dependencies. Runtime compatibility checks are listed in the repository release record; a lower bound is not proof of every runtime pair.

After publication, add this dependency to your project's mix.exs:

{:pll, "~> 0.1.0"}

Then run mix deps.get. The Hex package contains the library, not the repository's benchmark or pacing scripts. The library starts no processes or application callbacks.

First useful example

All times are integer nanoseconds, never floating seconds or implicit clocks. Every state transition returns a new value; callers must retain it.

alias PLL.{Pacer, Rate}

{:ok, rate} = Rate.units_per_second(48_000, 1)
{:ok, p0} = Pacer.new(rate)
{:ok, p1, a} = Pacer.due(p0, 0, 4096)
{:ok, p2, b} = Pacer.due(p1, 10_000_000, 4096)
{:ok, p3, c} = Pacer.due(p2, 25_000_000, 4096)
[{0, 1}, {1, 480}, {481, 720}] =
  Enum.map([a, b, c], fn span -> {span.first, span.count} end)
{:ok, {1201, 25_020_834}} = Pacer.next_due(p3)

At 10 ms slot 480 is exactly due; zero was already consumed. At 25 ms slot 1200 is due. The ceiling of 1201*10^9/48000 is 25,020,834 ns. A late call produces backlog, not silent loss. The caller chooses processing, caps or skips. Calling due again on p0 instead of p3 intentionally replays the original schedule: immutability does not enforce single consumption for the caller.

Public API

ns below means integer nanoseconds, ticks a signed integer counter. Opaque states/values are structs, never PIDs. First/count and observation fields are readable; callers must not manually alter structs or private fields. No bang-constructor, async, blocking or implicit-clock API is included.

Function / value Return shape and meaning
PLL.Rate.units_per_second(num, den) {:ok, rate} or error; gcd-reduced exact fraction.
PLL.Rate.bits_per_second(bits, bits_per_unit) Same fraction bits/bits_per_unit.
%PLL.Rate{} Invalid zero sentinel; num and den getters return 0. Construct valid values through factories.
PLL.Rate.num(rate), PLL.Rate.den(rate) Reduced integer terms.
PLL.Rate.to_string(rate) "48000 units/s", "30000/1001 units/s", or "invalid rate"; also the String.Chars protocol.
PLL.Pacer.new(rate) {:ok, pacer} or error; cursor/trim start at 0.
PLL.Pacer.due(pacer, now_ns, max_count) {:ok, next_pacer, span} or error.
PLL.Pacer.claim(pacer, n) {:ok, next_pacer, span} or error.
PLL.Pacer.skip(pacer, now_ns, keep) {:ok, next_pacer, skipped_count} or error.
PLL.Pacer.next_due(pacer) {:ok, {cursor_slot, first_due_ns}} or error.
PLL.Pacer.set_trim(pacer, ppt) {:ok, next_pacer} or error.
PLL.Pacer.trim(pacer) Integer ppt, no tagged wrapper.
%PLL.Span{} Empty zero span (first == count == 0); other manual construction unsupported.
span.first, span.count Read-only-by-contract issued extent.
PLL.Span.time(span, i) Floored ns at relative index i; raises Enum.OutOfBoundsError for integer i < 0 or i >= count.
PLL.Span.all(span) Fresh lazy Enumerable of {slot, ns} tuples; early termination avoids computing the rest.
PLL.FollowerConfig.default(nominal) Config struct, exact defaults below; no nominal validation yet.
%PLL.FollowerConfig{...} All ten fields below; omitted nominal is %PLL.Rate{}, omitted float fields are 0.0, omitted integer fields are 0 (an invalid zero config). Construct via default and struct update. No hidden config source.
PLL.Follower.new(config) {:ok, follower} or error; validates all fields. Initially unanchored.
PLL.Follower.observe(follower, local_ns, remote) {:ok, next_follower, observation} or error.
PLL.Follower.local(follower, remote) {:ok, local_ns} or error.
PLL.Follower.remote(follower, local_ns) {:ok, remote_ticks} or error.
PLL.Follower.offset(follower) Binary64 fractional rate offset y, no tagged wrapper.
PLL.Follower.trim(follower) Integer pacer-compatible ppt, no tagged wrapper.
PLL.Follower.jitter(follower) Integer RMS error ns, no tagged wrapper.
PLL.Follower.state(follower, now_ns) `{:ok, :acquiring
PLL.Follower.reset(follower) Fresh unanchored follower retaining config; direct state return, no error.
%PLL.Observation{status: status, error_ns: ns} Observation value; error_ns is phase error, not an error result.
PLL.Status.to_string(status) Status spelling described below.
PLL.State.to_string(state) State spelling described below.
PLL.Error.message(error) Stable human-readable error string described below.

Observation statuses are atoms :anchored, :accepted, :pending, :rejected, :stepped. States are :acquiring, :locked, :holdover. The status/state string functions accept these atoms and return lowercase names. For Go string compatibility they also accept byte integers: known status codes 1..5 map in that order, state codes 0..2 map in that order; unknown codes yield "Status(9)" or "State(9)" (including "Status(0)"). The library never emits unknown statuses. Unsupported terms/codes outside 0..255 raise ArgumentError. No mutable numeric enum objects are required.

Types, bounds and errors

Despite BEAM big integers, deliberately retain compatibility envelopes. U=2^64-1, Imin=-2^63, Imax=2^63-1. Rate terms and slot/count/cap/keep arguments are integers in 0..U; valid rate terms and claim/cap counts are positive. Pacer time inputs first fit signed 64-bit ns, then must be nonnegative. Follower local/now inputs and remote ticks fit signed 64-bit and may be negative. Config durations fit signed 64-bit; step_after and lock_count also use signed 64-bit (the 64-bit Go baseline, not platform-dependent Go int). Trim input fits signed 64-bit, then lies strictly between ±10^12. Integer intermediate arithmetic is unbounded and must not overflow or wrap.

All fallible functions in the table return only {:error, error} on failure, where error is %PLL.Error{code: code, field: field, reason: reason}. No replacement state or partial value is returned on failure; the caller retains the original immutable supplied state. Successful transformations put the new state before the output value, consistently. set_trim returns only state because it has no separate value. Queries never return a replacement state. state/2 is tagged because its now argument needs boundary validation; getters without scalar input and reset are direct returns.

code field/reason Error.message
:invalid_rate nil/nil pll: invalid rate
:invalid_argument nil/nil pll: invalid argument
:overflow nil/nil pll: overflow
:order nil/nil pll: reading out of order
:not_anchored nil/nil pll: follower has no reading yet
:config snake-case field atom / reason string below pll: FollowerConfig.<field> <reason>

For scalar inputs to fallible functions, wrong types return invalid_argument; integers outside their input envelopes return overflow before semantic checks. Zero within-envelope rate terms return invalid_rate. Negative within-signed- envelope pacer time, zero claim/cap, or out-of-open-interval trim returns invalid_argument. Negative unsigned arguments are outside the envelope, not wrapped. Validate all scalar argument types/envelopes left-to-right before any semantic checks. Thus Rate.units_per_second(0,U+1) and Pacer.due(p,-1,U+1) return overflow; a first scalar wrong type takes priority over a later out-of-envelope integer. Then apply semantic checks. Struct/state of the wrong kind is programmer misuse and raises ArgumentError, rather than fabricating a controller. Span.time's non-integer index raises ArgumentError; integer invalid indexes raise Enum.OutOfBoundsError rather than returning tagged results.

Config validation traverses fields in the table order, checking field type, then envelope, then semantic rule. Wrong types and semantic violations return :config with that field's listed reason; an integer beyond its envelope returns :overflow. The three float fields require floats, not integers. Elixir normally cannot construct NaN/Infinity float terms; there is no string parser or nonfinite sentinel API. Nonfinite floating values, if supported by a supported runtime boundary, must be rejected with the field's config reason. Valid extreme finite inputs must still work without leaking arithmetic exceptions from overflowing intermediate gain products.

Every failure preserves supplied state and issued spans, whether a tagged error or a documented argument/index exception. Pending/rejected observations are successful transitions: their order/window/outlier metadata can change. No hidden process or mutable store can change old snapshots. Match error codes and fields rather than parsing messages. Go's nil/zero error outputs are adapted to the absence of a success tuple; do not return both a value and an error.

Exact pacer contract

The nominal rate is reduced num/den units per second. Slots start at zero and the cursor marks the next neither issued nor skipped. On one retained state chain the cursor never decreases. Slot U is never issued or skipped, though cursor U is allowed, so first+count<=U. A segment has start S, integer ns anchor A and trim q ppt:

T(s) = A + (s-S) * den * 10^21 / (num * (10^12 + q)), s >= S
initially S=0, A=0, q=0

Use exact integer/rational arithmetic even with 64-bit rate terms, huge slot indexes and q=±(1012-1). Period reduction/representation is private; no Go fast path is required. Span.time is floor(T). Due compares exact T<=now, not its floor: at period 8/3 ns slot 1 has time 2 but first becomes due at 3. Above 109 units/s, several slots can share a ns; times stay non-decreasing.

An issued span covers first..first+count-1 and carries timing independently of the pacer's lifetime. Treat it as read-only. Empty spans enumerate zero tuples and have no valid time index. Manually altered/forged structs have no timing guarantees. Issuing a span must not materialize its potentially enormous slots.

More hand-checkable pacing examples

alias PLL.{Pacer, Rate, Span}

{:ok, rate} = Rate.units_per_second(60_000, 2002)
{30_000, 1001, "30000/1001 units/s"} =
  {Rate.num(rate), Rate.den(rate), Rate.to_string(rate)}
{:ok, p0} = Pacer.new(rate)
{:ok, _p1, span} = Pacer.claim(p0, 4)
[{0, 0}, {1, 33_366_666}, {2, 66_733_333}, {3, 100_100_000}] = Enum.to_list(Span.all(span))
{:ok, byte_rate} = Rate.bits_per_second(50_000_000, 8)
{:ok, bytes0} = Pacer.new(byte_rate)
{starts, _bytes3} = Enum.map_reduce([1500, 400, 1500], bytes0, fn n, p ->
  {:ok, next, s} = Pacer.claim(p, n)
  {Span.time(s, 0), next}
end)
[0, 240_000, 304_000] = starts
{:ok, rate} = Rate.units_per_second(1000, 1)
{:ok, p0} = Pacer.new(rate)
{:ok, p1, 8} = Pacer.skip(p0, 10_000_000, 3)
{:ok, p2, old} = Pacer.due(p1, 10_000_000, 3)
[{8, 8_000_000}, {9, 9_000_000}, {10, 10_000_000}] = Enum.to_list(Span.all(old))
{:ok, p3} = Pacer.set_trim(p2, -500_000_000_000)
{:ok, _p4, slow} = Pacer.claim(p3, 3)
[{11, 11_000_000}, {12, 13_000_000}, {13, 15_000_000}] = Enum.to_list(Span.all(slow))
10_000_000 = Span.time(old, 2)

Boundary fixture: rate (2_000_000_000,U) has period Imax+1/2 ns. After claiming slot 0, next_due overflows; due(Imax,1) is empty at first=1; claim(1) succeeds with time Imax. At rate (U,1), claim(U) reaches cursor U; due(0,1) is empty but due(109,1), skip(109,0), claim(1) and next_due all overflow. These must remain cheap span operations, not enumerate enormous lists.

Follower configuration (all defaults and validation)

Start with PLL.FollowerConfig.default(rate), then %{cfg | window_ns: ...}. The config is immutable; changing a separate config value cannot reconfigure an existing follower. Construct a new follower to change settings. Table order is validation order. Reasons are exact strings; port field spellings replace Go's CamelCase in errors.

Elixir field (Go field) Type Default Invalid when / config reason
nominal (Nominal) Rate supplied rate invalid/zero rate: must be a valid Rate
bandwidth_hz (Bandwidth) float 0.1 nonfinite or <=0: must be finite and > 0
damping (Damping) float sqrt(2)/2 nonfinite or <=0: must be finite and > 0
max_offset_ppm (MaxOffsetPPM) float 500.0 nonfinite, <=0 or >=1000000: must be finite, > 0 and < 1000000
window_ns (Window) integer 0 <0: must be >= 0
outlier_threshold_ns (OutlierThreshold) integer 5_000_000 <=0: must be > 0
step_after (StepAfter) integer 3 <1: must be >= 1
lock_threshold_ns (LockThreshold) integer 100_000 <0: must be >= 0
lock_count (LockCount) integer 8 <1: must be >= 1
holdover_after_ns (HoldoverAfter) integer 5_000_000_000 <=0: must be > 0

Defaults target low-jitter readings. A suggested, never automatic, network profile from Go uses bandwidth 0.005 Hz, window 1_000_000_000 ns, lock threshold 2_000_000 ns and outlier threshold 20_000_000 ns, other defaults unchanged. This trades settling speed for filtering; source simulator measured lock times and accuracy are not promises about this port.

Follower state machine and numerical contract

Local ns uses a caller-chosen origin, possibly negative; remote ticks are already unwrapped signed integers. Nominal period Pn=float(den)*1e9/float(num) is binary64 ns. Retain integer local anchor I0 plus binary64 fraction frac, remote anchor R0 and rate offset y. Initially unanchored, y=0, jitter=0, acquiring. This is an immutable state value, not an autonomous process.

predicted(r) = I0 + frac + (r-R0)*Pn/(1+y)
e = local - predicted(r)            # positive means arrived late
remote speed = nominal * (1+y)

For a difference fitting signed 64-bit, subtract integers first, then convert the difference to float. Preserve small differences at huge absolute times. If it exceeds signed 64-bit, use float(a)-float(b) as Go does, not wrapping or converting absolute anchors for ordinary small displacements. Converting large differences beyond 2^53 can lose low bits. Rebase on every loop update with integer plus fractional local anchors, avoiding loss solely from uptime.

observe, in order

  1. After the first reading, local must be >= the last successful reading's local and remote strictly greater than its remote. Otherwise return order. Previous includes pending/rejected/stepped, not failed calls.
  2. First reading (also after reset) anchors exactly to (local,remote), y=0, clears histories and returns anchored with error_ns=0.
  3. With window_ns=0, feed each later reading. With window_ns>0, the first later reading opens a window at its local time and becomes candidate; return pending with error_ns=0. Within its half-open window, replace candidate only for a strictly smaller signed phase error, not smaller absolute error. Ties keep the earlier candidate. Mapping stays fixed while window is open.
  4. On elapsed local >= window_ns, feed the old candidate, return that result, then open a new window with the triggering reading. Compute its candidate error against mapping after flush. Compare elapsed time exactly even across signed-time extremes; do not overflow start+window. No timer or flush API exists: the final pending candidate waits for another boundary reading. Returned error and last accepted time refer to the candidate, not necessarily the input which caused the flush.
  5. If feeding overflows the new integer local anchor, return overflow and no next state: candidate, order, window, outlier and all other supplied state remain available unchanged. No partial successful transition is exposed.

Feeding a sample

Use unrounded binary64 phase error e in ns. For phase-domain comparisons, convert outlier_threshold_ns and lock_threshold_ns to binary64 (as in the pinned Go source); do not use BEAM exact mixed float/integer comparison. Input envelopes, order and elapsed duration comparisons remain exact integers.

Accepted/rejected/stepped observation.error_ns is round_away(e), saturated to [Imin,Imax]; anchored/pending errors are zero. A finite phase error outside the signed duration range is not itself a failure.

Queries, rounding, holdover and reset

round_away means nearest integer, half ties away from zero. Mapping rounds displacement, not absolute time:

Binary64 follower estimates are not exact rational time. Arbitrarily distant extrapolation is not nanosecond-accurate, and round trips can lose ticks/ns. There is no exact inverse or universal bit-identical cross-runtime float promise. Rounding, integer anchoring and saturation rules still apply. At a 0.5 ns period with anchor (local=1,remote=0), local(-1) is 1+round_away(-0.5)=0; with anchor (-1,0), local(1) is 0.

Cross-module success and failure

alias PLL.{Error, Follower, FollowerConfig, Pacer, Rate, Span}

{:ok, rate} = Rate.units_per_second(1000, 1)
cfg = %{FollowerConfig.default(rate) | bandwidth_hz: 1.0, damping: 1.0}
{:ok, f0} = Follower.new(cfg)
{:error, %Error{code: :not_anchored}} = Follower.local(f0, 0)
{:ok, f1, %{status: :anchored, error_ns: 0}} = Follower.observe(f0, 0, 0)
# 1 ms late, dt=1.001 s, x=0.5, kp=1:
{:ok, f2, %{status: :accepted, error_ns: 1_000_000}} = Follower.observe(f1, 1_001_000_000, 1000)
{:ok, 1_001_000_000} = Follower.local(f2, 1000)
-249_750_250 = Follower.trim(f2)  # y = -0.25 / 1.001 * 0.001
{:ok, p0} = Pacer.new(rate)
{:ok, p1, _initial} = Pacer.claim(p0, 1000)
{:ok, p2} = Pacer.set_trim(p1, Follower.trim(f2))
{:ok, p3, span} = Pacer.claim(p2, 2)
[{1000, 1_000_000_000}, {1001, 1_001_000_249}] = Enum.to_list(Span.all(span))
before = {Follower.offset(f2), Follower.local(f2, 1000), Pacer.next_due(p3), Pacer.trim(p3)}
{:error, %Error{code: :order}} = Follower.observe(f2, 1_001_000_000, 1000)
{:error, %Error{code: :invalid_argument}} = Pacer.set_trim(p3, 1_000_000_000_000)
^before = {Follower.offset(f2), Follower.local(f2, 1000), Pacer.next_due(p3), Pacer.trim(p3)}
bad = %{FollowerConfig.default(rate) | bandwidth_hz: 0.0, lock_count: 0}
{:error, %Error{code: :config, field: :bandwidth_hz, reason: "must be finite and > 0"}} = Follower.new(bad)
# There is no next-state value to accidentally retain from a failed transition.

Additional deterministic workflows, each starting from a fresh follower and retaining each successful next state:

Inputs/settings Promised outcome
Default 1000 ticks/s; observe(0,0), then (k10_000_000,k10), k=1..8 Anchored, eight accepted errors 0; offset/trim/jitter 0; locked at 80 ms. At now=5_080_000_000 still locked, at 5_080_000_001 holdover. State results are tagged ok tuples.
Same defaults; anchor(0,0), then (10_000_000,2010),(20_000_000,2020),(30_000_000,2030) Errors -2_000_000_000: rejected, rejected, stepped; y=0, local(2030) returns ok 30_000_000; acquiring, jitter 0.
Rate 10^9, window_ns=4; (0,0),(1,1),(4,4),(5,5) Anchored, pending, pending, accepted; equal errors retain candidate (1,1), (5,5) opens next window. Last accepted=1, not 5.
Rate 10^9; anchor(Imax,0); local(1) Tagged overflow; original immutable follower unchanged.

Ownership, effects and concurrency

All values, including Pacer/Follower states and configuration, are immutable. Each transition produces a new state (or an equivalent unchanged value for a no-op). Internal immutable segments can be shared; issued spans retain old segment timing. Freely share snapshots between processes, but one logical schedule/loop should have one owner retaining the current state. Concurrent branches from an old snapshot can issue overlapping slots or learn divergent mappings; that is replay, not global coordination. The library does not serialize callers or start an owner process. Configuration updates never alter followers already created. Mutating struct fields by hand/forging state is unsupported; no persistence or serialized layout is promised.

The library performs no I/O, network access, timers, sleeping, process/task creation, implicit clock reads, environment reads or credential access. It only transforms in-memory timing/config/history and never touches payloads. Caller adapters provide monotonic elapsed ns, consistent origins, clock reads, remote-counter unwrapping, wakeups, OTP ownership/cancellation, backpressure, queues, devices and transport. Pacer earlier-now tolerance is not follower input-order tolerance; adapters must distinguish them.

Build/test execution is separate from library runtime: Mix/ExUnit start VM/test processes and write _build/compiler caches; format can write sources. Such explicit development-tool effects do not contradict the runtime contract. The deterministic checks require no network or credentials.

Verification

From the repository root:

mix format --check-formatted
mix compile --warnings-as-errors
mix test --seed 0

Tests cover exact pacing against an independent rational oracle, immutable snapshots, validation and failure preservation, follower windows/outliers/steps, synthetic-clock scenarios and pinned public-Go fixtures. See corpus documentation for provenance and numerical tolerances. Finite fixtures do not establish universal parity, real-device behavior or portable performance. Historical results are recorded in Stage 3 verification.

Throughput benchmark

This dependency-free developer harness measures this Elixir implementation, not Go speed or real-time scheduling. It is separate from the pure runtime library. The harness uses the public library API and runs bounded workloads.

mix run scripts/throughput.exs --smoke
mix run scripts/throughput.exs
mix run scripts/throughput.exs --iterations 1000 --samples 3 --warmup 100

No environment configuration, config files, workload selection or positional arguments. --smoke must stand alone: 12 iterations, 2 samples, 4 warmup iterations per workload. Otherwise defaults are 1000 iterations, 3 samples, 100 warmup. Each integer must be canonical positive decimal; iterations/warmup <=10000, samples <=10; unknown, duplicate, missing, malformed or oversized options fail with stderr and exit 2 before workloads. At most 900000 measured logical ops plus 90000 warmup ops across all nine workloads; each op is bounded (span visits 64 items). These bound work, not elapsed wallclock on arbitrary hardware.

Each workload warms up once, then prepares a fresh independent state outside each sample's timer, and chains every next immutable state within that sample. Workloads/samples run sequentially, no sleeping or live observation timestamps. All library input clocks are deterministic integer counters. The harness uses only public library calls, not private fields or an external implementation.

Workload One logical op; units per op
due_one Pacer.due at i-1 ns, cap 1; 1 issued slot
due_batch Pacer.due at 64*i-1 ns, cap 64; 64 issued slots
claim Pacer.claim(1500); 1500 issued slots
skip Pacer.skip at 64*i-1 ns, keep 0, plus next_due sink query; 64 skipped slots
span Fully reduce Span.all over a preissued 64-slot span into sum(slot+ns); 64 generated tuples
inlier Follower.observe at (10i,10i); 1 reading, accepted
window observe(i,i), window_ns=4; 1 reading; accepted floor((n-1)/4), remaining pending
outlier observe(10i,10i+100), threshold 10, step_after=n+1; 1 reading, rejected
step observe(10i,10i+100*ceil(i/3)), threshold 10, step_after=3; 1 reading; floor(n/3) stepped, remaining rejected

All rates are 10^9 units/s (1 ns period), zero pacer trim. Followers use default config except those listed (both outlier_threshold_ns and lock_threshold_ns are 10 ns for every follower workload); each sample anchors at (0,0) outside timing. Warmup uses its own n for outlier step_after. Issuance does not enumerate spans: checksum adds first+count. Skip checksum adds next cursor+due time. Follower checksum adds observation error+input local+remote; status counts are observed, not assumed. Validate actual calls, units and exact status distributions after timing; mismatch raises rather than mislabels a row. Span enumeration is intentionally separate from issuance and repeatedly consumes the same immutable span, generating every tuple anew. Other workloads must not repeatedly use initial states. Checksums/counts are emitted, never dead sinks.

Header labels: schema name pll-throughput-v1, Elixir/OTP, system architecture, online schedulers, config and library_revision, pinned to the protected library baseline 03a99baca1db2872f6e6f9298914aab9e2242a2a. This identifies library code, NOT the benchmark implementation's checkout SHA/dirty status; record git rev-parse HEAD separately when comparing local runs. No environment dump. One stdout map per sample includes workload/sample, calls, units, statuses, checksum and the following non-aggregated metrics:

Nonpositive measured elapsed time fails rather than divides by zero. Output, metadata, warmup and setup are outside timing. Retained state lives through the second clock; a report keeps scalar sinks/counts, not a permanent state history. No thresholds, automatic tuning, Go comparison claims or statistical confidence claims; short smoke times are only finite execution evidence. Repeat samples and inspect noise before drawing conclusions.

Tool-only effects are explicitly permitted: monotonic clock reads, process memory and VM-wide GC introspection, runtime/platform queries and stdout/stderr. Mix may write ignored build caches/start VM processes as usual. The harness itself does not write results, spawn workload processes, read environment/secrets, contact network, sleep or tune VM globals. No permanent results/artifact format is added.

Local real-time pacing demonstration

This checkout-only tool drives discard or local UDP with the Elixir pacer. It is separate from the pure library and the throughput microbenchmark. It supports pacer mode only: no ticker, rate search, remote destinations or arbitrary payloads. Writer acceptance does not measure receipt or loss. Historical same-machine results and their limits are recorded in pacing verification.

Commands and effects

Run from the repository root:

mix run scripts/pacing.exs
mix run scripts/pacing.exs --bps 19392658 --unit-bytes 188 --seconds 5
mix run scripts/pacing.exs --bps 19392658 --unit-bytes 188 --seconds 5 --udp loopback --per-datagram 1
mix run scripts/pacing.exs --bps 19392658 --unit-bytes 188 --seconds 5 --udp loopback --per-datagram 7

Defaults: 19,392,658 bps, 188 bytes, 5 seconds, discard, grouping 1, pacer only. This is approximately ATSC payload rate: 12,894.0545 units/s, 77.5551 microseconds/unit. Zero-filled bytes are timing payload, not valid MPEG-TS. No flags means no network. Only literal --udp loopback enables IPv4 127.0.0.1, ephemeral ports, one receiver reading/discarding and one sender; no DNS, remote destination, file payload or result file. Receiver read buffer request 8 MiB is best-effort and not evidence of effective buffer size.

Only the shown value flags are supported. No config/environment inputs, positional arguments, unknown/duplicate/missing options or alternative destinations. All numeric strings canonical positive decimals: bps 1..100000000, unit bytes 1..65507, seconds integer 1..10, per-datagram 1..65507 with product <=65507 (even in discard, where effective grouping is 1). Before allocation, timers or sockets, validate all types/products plus 1+ceil(bps*seconds/(8*unit_bytes)) <=1000000. Also cap actual offers and calls/lateness samples at 1,000,000 each; cap exhaustion is an incomplete failed trial, not a sustained result. Due cap 4096 is fixed. Bounds are tool constraints, not library API changes.

Tool-only effects: clocks, cancellable timed waits, bounded coordinator/worker and loopback receiver processes, local sockets, runtime metadata and stdout/stderr; Mix build caches as usual. No installs, dependencies, subprocess comparison runner, VM-global tuning, secrets, persistent results or external actions. The tool does not launch Go comparisons. Report revision/dirty state separately using operator Git commands, plus runtime/platform/schedulers and all effective options with each comparison. No environment dump.

Timing and failures

Isolated scripts/pacing.exs entrypoint and scripts/pacing/ helpers, using only public PLL.Rate, PLL.Pacer, PLL.Span; no private fields/algorithm changes. A single worker retains each returned immutable pacer state, origin and counters; there is no shared mutable schedule or implicit library clock. Inject tool-local clock/wait/writer seams for deterministic tests, not a new public library API.

Use System.monotonic_time(:nanosecond)-origin integer offsets. After processing a span, recompute remaining time to next due/deadline; if positive use a cancellable receive timeout rounded up to whole milliseconds. Do not use Process.sleep as a microsecond timer, repeated zero-time polling, busy-spin waiting or scheduler changes. Coarse wakeups intentionally produce batches; when already overdue, immediately drain another capped batch, checking deadline and cancellation between calls and cancellation between units. Never skip to hide backlog. Normal deadline stops new calls, finishes current batch and flushes partial grouping; include final write in elapsed and backlog as Go does.

Coordinator monitors worker/receiver, imposes duration+2 seconds runtime guard (excluding Mix startup), and kills the worker if it does not stop. Cooperative cancellation is an internal injected/test seam, not an operator-exposed command or signal API; the production coordinator does not send cancellation messages. Worker owns sender socket; receiver owns read socket. Normal/error paths close resources and terminate receiver; process death must release owned sockets and pending timers. Cancellation aborts buffered output, reports incomplete/nonzero, never a sustained verdict. Socket/open/read/send/flush failures stop the trial; no retries, cross-trial buffers or false accepted counts. UDP success counts whole datagram payload only, not receipt. Fake writer tests cover partial/error accounting even though the UDP adapter reports whole-send success or error. Ctrl-C/VM termination may prevent a final report; it is not a successful trial. Wall guard is a safety bound subject to OS/VM scheduling, not a hard real-time SLA.

Report target, offered units, accepted payload bytes, elapsed ns, writer Mbps, backlog ns, call/wake-up count, average/max units per call, nonempty lateness sample count and median/p99/max ns with Go's quantile rule; distinguish effective datagram grouping and send-call count from Due-call count. Print roughly once/second like Go, inside timing. Go lacks a send-call metric, so do not claim identical output. Report completed/deadline/error/cancel/cap/guard stop reason and timing verdict. sustained is timing-only (nonempty deadline completion, backlog and p99 bounds); demonstration_pass additionally checks accepted-byte accounting and bitrate. The CLI exits 0 on deadline completion, not on a passing demonstration verdict; operators must inspect demonstration_pass and record every failed trial. Slot zero is due immediately: short runs can appear fast by up to about one unit; no start-slot subtraction or forced unit-count equality across runtimes. Backlog is cursor lag, not queue depth. Lateness is oldest scheduled unit at call entry, not each unit's send time, network/receiver jitter or a bound on every unit.