Tool · Elixir library · Pre-release

pll: Exact Pacing and Clock Following for Elixir

Rational pacing and phase-locked clock following with immutable state.

README.md

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:

elixir
1{: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.

elixir
 1alias PLL.{Pacer, Rate}
 2
 3{:ok, rate} = Rate.units_per_second(48_000, 1)
 4{:ok, p0} = Pacer.new(rate)
 5{:ok, p1, a} = Pacer.due(p0, 0, 4096)
 6{:ok, p2, b} = Pacer.due(p1, 10_000_000, 4096)
 7{:ok, p3, c} = Pacer.due(p2, 25_000_000, 4096)
 8[{0, 1}, {1, 480}, {481, 720}] =
 9  Enum.map([a, b, c], fn span -> {span.first, span.count} end)
10{: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 / valueReturn 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.countRead-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.

codefield/reasonError.message
:invalid_ratenil/nilpll: invalid rate
:invalid_argumentnil/nilpll: invalid argument
:overflownil/nilpll: overflow
:ordernil/nilpll: reading out of order
:not_anchorednil/nilpll: follower has no reading yet
:configsnake-case field atom / reason string belowpll: 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:

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

Use exact integer/rational arithmetic even with 64-bit rate terms, huge slot indexes and q=±(10^12-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 10^9 units/s, several slots can share a ns; times stay non-decreasing.

  • due: negative now or zero cap is invalid. Find exact largest due slot L, capped at U. If none at/after cursor is due, return empty span at first=cursor and unchanged logical state. If cursor U itself is due, overflow. Otherwise issue cursor..min(L,U-1), at most max_count, oldest first, and advance. Earlier now values are allowed and may still drain their due backlog.
  • claim: zero n invalid. Overflow if n>U-cursor or the last slot’s floor exceeds Imax; otherwise issue/advance, whether due or not.
  • skip: D is how many slots due could issue ignoring its cap, excluding U. Advance by D-min(D,keep), returning that count. keep=0 skips all available due slots. Negative now invalid; cursor U with that slot due overflows even if keep would retain it. For k>0, skip(now,k) then due(now,k) on the returned state yields newest k available due slots (or fewer if fewer available). For k=0 do not subsequently call due with a zero cap.
  • next_due: cursor and ceil(T(cursor)); overflow for cursor U or a ceiling beyond Imax. A floor may fit even when its ceiling does not.
  • set_trim: reject q<=-10^12 or q>=10^12. If unchanged, true no-op with no re-anchoring, even if cursor time cannot fit. Otherwise new S=cursor, A=floor(T_old(cursor)), q=new trim; overflow if A>Imax. Anchoring at floor moves phase earlier by less than 1 ns, preserves non-decreasing times and prevents accumulating fractional anchors. Previously issued spans keep their original segment timing; changing a later pacer never changes them.

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

elixir
 1alias PLL.{Pacer, Rate, Span}
 2
 3{:ok, rate} = Rate.units_per_second(60_000, 2002)
 4{30_000, 1001, "30000/1001 units/s"} =
 5  {Rate.num(rate), Rate.den(rate), Rate.to_string(rate)}
 6{:ok, p0} = Pacer.new(rate)
 7{:ok, _p1, span} = Pacer.claim(p0, 4)
 8[{0, 0}, {1, 33_366_666}, {2, 66_733_333}, {3, 100_100_000}] = Enum.to_list(Span.all(span))
 9{:ok, byte_rate} = Rate.bits_per_second(50_000_000, 8)
10{:ok, bytes0} = Pacer.new(byte_rate)
11{starts, _bytes3} = Enum.map_reduce([1500, 400, 1500], bytes0, fn n, p ->
12  {:ok, next, s} = Pacer.claim(p, n)
13  {Span.time(s, 0), next}
14end)
15[0, 240_000, 304_000] = starts
16{:ok, rate} = Rate.units_per_second(1000, 1)
17{:ok, p0} = Pacer.new(rate)
18{:ok, p1, 8} = Pacer.skip(p0, 10_000_000, 3)
19{:ok, p2, old} = Pacer.due(p1, 10_000_000, 3)
20[{8, 8_000_000}, {9, 9_000_000}, {10, 10_000_000}] = Enum.to_list(Span.all(old))
21{:ok, p3} = Pacer.set_trim(p2, -500_000_000_000)
22{:ok, _p4, slow} = Pacer.claim(p3, 3)
23[{11, 11_000_000}, {12, 13_000_000}, {13, 15_000_000}] = Enum.to_list(Span.all(slow))
2410_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(10^9,1), skip(10^9,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)TypeDefaultInvalid when / config reason
nominal (Nominal)Ratesupplied rateinvalid/zero rate: must be a valid Rate
bandwidth_hz (Bandwidth)float0.1nonfinite or <=0: must be finite and > 0
damping (Damping)floatsqrt(2)/2nonfinite or <=0: must be finite and > 0
max_offset_ppm (MaxOffsetPPM)float500.0nonfinite, <=0 or >=1000000: must be finite, > 0 and < 1000000
window_ns (Window)integer0<0: must be >= 0
outlier_threshold_ns (OutlierThreshold)integer5_000_000<=0: must be > 0
step_after (StepAfter)integer3<1: must be >= 1
lock_threshold_ns (LockThreshold)integer100_000<0: must be >= 0
lock_count (LockCount)integer8<1: must be >= 1
holdover_after_ns (HoldoverAfter)integer5_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.

text
1predicted(r) = I0 + frac + (r-R0)*Pn/(1+y)
2e = local - predicted(r)            # positive means arrived late
3remote 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.

  • If abs(e)>outlier_threshold_ns, it is an outlier. A run continues only when abs(e-e_first)<=threshold, comparing with the first error in the run; otherwise start a new run of length 1. At step_after, re-anchor exactly to the fed sample, keep y, clear lock/jitter/outlier run, record its local as last accepted and return stepped. Otherwise return rejected: mapping, lock, jitter and last accepted stay unchanged, but order and outlier metadata can change in the new state. An inlier ends the run only on successful feed.

  • For an inlier, dt is local seconds from last anchor/step/loop update. If dt>0, use the old mapping to compute:

    text
    1wn = 2*pi*bandwidth_hz
    2x = min(0.5, wn*dt)
    3kp = min(1, 2*(damping*x))
    4y_new = clamp(y - (x*x/dt)*e/1e9, -max_offset_ppm*1e-6, +max_offset_ppm*1e-6)
    5v = (predicted_old(remote)-I0) + kp*e
    6whole = round_away(v)
    7I0_new = I0 + whole; frac_new = v-whole; R0_new = remote

    Check I0_new against signed 64-bit before returning new state; update the loop reference time to sample local. The capped product stabilizes sparse readings and extreme finite gains. Evaluate caps without generating an overflowing float or arithmetic exception: BEAM does not expose Go-style Infinity intermediates. Do not cap dt first and then multiply Infinity by zero. All positive finite bandwidth/damping inputs, including binary64 extremes, must work. With dt=0 mapping/rate/reference do not change.

  • Every accepted inlier, including dt=0, increments lock run up to lock_count if abs(e)<=lock_threshold_ns; otherwise clears it. Equality counts.

  • Jitter: first accepted inlier after anchor/step/reset sets m=e*e; later accepted inliers use m += (e*e-m)/16. Record sample local as last accepted and return accepted. Anchor/step do not count as jitter samples. Jitter is 0 until two accepted inliers, then round_away(sqrt(m)) ns, saturated to signed duration range. Use unrounded e, not observation.error_ns.

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:

  • local(r) = I0 + round_away(frac + (r-R0)*Pn/(1+y)).
  • remote(l) = R0 + round_away(((l-I0)-frac)*(1+y)/Pn).
  • Both return not_anchored before anchoring, overflow if final result does not fit signed 64-bit. Add rounded whole displacement exactly to integer base, preserving base low bits. Allow displacement outside signed 64-bit when it cancels with the anchor to a fitting result; retain Go wide-displacement behavior. Never reject solely because displacement itself exceeds Imax.
  • offset returns y. trim returns round_away(y*10^12), saturated to ±999_999_999_999, always inside Pacer.set_trim’s range even at near-maximum offset. set_trim may still overflow a particular pacer’s new anchor; updating two controller states is the caller’s responsibility, not a shared transaction.
  • state(now) returns holdover iff anchored and now-last_accepted>holdover_after_ns, using exact elapsed comparison across signed range. Equality is not holdover; earlier now is allowed. Otherwise locked if lock run reached lock_count, acquiring if not (also before anchoring). Pending/rejected readings do not refresh last accepted. Holdover is only a query result: mapping continues at last estimated rate; it does not start/stop a timer or change loop state.
  • reset forgets mapping, y, input order, window, outlier run, lock and jitter, retaining config. The next reading may anchor at an earlier time/tick.

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

elixir
 1alias PLL.{Error, Follower, FollowerConfig, Pacer, Rate, Span}
 2
 3{:ok, rate} = Rate.units_per_second(1000, 1)
 4cfg = %{FollowerConfig.default(rate) | bandwidth_hz: 1.0, damping: 1.0}
 5{:ok, f0} = Follower.new(cfg)
 6{:error, %Error{code: :not_anchored}} = Follower.local(f0, 0)
 7{:ok, f1, %{status: :anchored, error_ns: 0}} = Follower.observe(f0, 0, 0)
 8# 1 ms late, dt=1.001 s, x=0.5, kp=1:
 9{:ok, f2, %{status: :accepted, error_ns: 1_000_000}} = Follower.observe(f1, 1_001_000_000, 1000)
10{:ok, 1_001_000_000} = Follower.local(f2, 1000)
11-249_750_250 = Follower.trim(f2)  # y = -0.25 / 1.001 * 0.001
12{:ok, p0} = Pacer.new(rate)
13{:ok, p1, _initial} = Pacer.claim(p0, 1000)
14{:ok, p2} = Pacer.set_trim(p1, Follower.trim(f2))
15{:ok, p3, span} = Pacer.claim(p2, 2)
16[{1000, 1_000_000_000}, {1001, 1_001_000_249}] = Enum.to_list(Span.all(span))
17before = {Follower.offset(f2), Follower.local(f2, 1000), Pacer.next_due(p3), Pacer.trim(p3)}
18{:error, %Error{code: :order}} = Follower.observe(f2, 1_001_000_000, 1000)
19{:error, %Error{code: :invalid_argument}} = Pacer.set_trim(p3, 1_000_000_000_000)
20^before = {Follower.offset(f2), Follower.local(f2, 1000), Pacer.next_due(p3), Pacer.trim(p3)}
21bad = %{FollowerConfig.default(rate) | bandwidth_hz: 0.0, lock_count: 0}
22{:error, %Error{code: :config, field: :bandwidth_hz, reason: "must be finite and > 0"}} = Follower.new(bad)
23# 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/settingsPromised outcome
Default 1000 ticks/s; observe(0,0), then (k10_000_000,k10), k=1..8Anchored, 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:

sh
1mix format --check-formatted
2mix compile --warnings-as-errors
3mix 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.

sh
1mix run scripts/throughput.exs --smoke
2mix run scripts/throughput.exs
3mix 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.

WorkloadOne logical op; units per op
due_onePacer.due at i-1 ns, cap 1; 1 issued slot
due_batchPacer.due at 64*i-1 ns, cap 64; 64 issued slots
claimPacer.claim(1500); 1500 issued slots
skipPacer.skip at 64*i-1 ns, keep 0, plus next_due sink query; 64 skipped slots
spanFully reduce Span.all over a preissued 64-slot span into sum(slot+ns); 64 generated tuples
inlierFollower.observe at (10i,10i); 1 reading, accepted
windowobserve(i,i), window_ns=4; 1 reading; accepted floor((n-1)/4), remaining pending
outlierobserve(10i,10i+100), threshold 10, step_after=n+1; 1 reading, rejected
stepobserve(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:

  • elapsed_ns: monotonic nanoseconds around execute only, including loop, state threading, accounting and sink overhead; not a pure isolated API latency.
  • ns_per_op = elapsed_ns/calls; ops_per_s = calls*10^9/elapsed_ns.
  • units_per_s = units*10^9/elapsed_ns. Slots/tuples/readings differ as above: do not confuse batch unit throughput with call throughput.
  • process_memory_delta_bytes: self process memory after minus before sample, signed bytes (may be negative). Not peak memory or allocation volume.
  • vm_gc_count_delta and vm_reclaimed_words_delta: differences of BEAM VM-wide :erlang.statistics(:garbage_collection) counters, including unrelated work; reclaimed words, not bytes/allocations or per-op allocations. Introspection brackets the timer and includes some measurement/validation bookkeeping (but validation itself occurs after the second snapshot). No forced GC.

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:

sh
1mix run scripts/pacing.exs
2mix run scripts/pacing.exs --bps 19392658 --unit-bytes 188 --seconds 5
3mix run scripts/pacing.exs --bps 19392658 --unit-bytes 188 --seconds 5 --udp loopback --per-datagram 1
4mix 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.