Part 1 of 2 · Keeping Time: Pacing Output and Following Clocks with a Phase-Locked Loop (PLL)
Keeping Time: Pacing and Following
A Go library for scheduling steady output and making sense of timestamps that arrive unevenly.
You can lead a packet to the IP stack, but you can’t make it leave.
At least, not at precisely the instant you intended. Your Go program can calculate when a packet should leave, but the operating system and network hardware have their own queues and schedules. The useful question is what your program can control — and how it handles the delays it can’t.
That distinction matters when you’re producing a steady stream of data. Your program might wake late, receive input in bursts, or spend longer than expected writing output. You still need to know what should have happened by now and what work remains.
pll is a fast, small Go library that provides two tools:
- A Pacer calculates scheduled times at an exact rate and identifies which scheduled opportunities are ready.
- A Follower estimates the relationship between a source’s clock and local time from repeated observations.
Neither reads the system clock, starts a goroutine, or sends data. Your application measures elapsed time and passes it to the library. The pacer calculates which slots are ready; your application sends the packets and decides when to check again.
Why I wrote it: MPEG-TS demuxer/remuxer
An MPEG transport stream is a sequence of 188-byte packets carrying video, audio, captions, and information a receiver needs to interpret them. A stream can contain several programs, with their packets interleaved.
My project takes programs from incoming streams and recombines them into new outgoing streams. Separating the inputs is demultiplexing; combining the selected content is multiplexing.
For an ATSC 1.0 broadcast channel, the outgoing transport stream runs at approximately 19.392 Mbps. That means about 12,894 packets per second, or one every 77.56 microseconds. The output needs to maintain that rate, using null packets as padding when there isn’t enough content.
The inputs introduce another timing problem. Some packets carry a program clock reference, or PCR: a sample of an encoder’s 27 MHz clock.1 Those readings describe the source’s timing, but packets can reach the application in uneven batches.
So the muxer needs both a steady output schedule and a way to interpret incoming timing information. They are related requirements, but they don’t need the same implementation.
Pacing: calculate what should be ready
My first implementation woke once per packet. A feedback controller measured whether output was ahead or behind and adjusted the timer. Using this approach, I was only able to reach about half the 19.392 Mbps rate I wanted.
There was a simpler question I could use, though: given the elapsed time and the requested rate, how many packets should be ready? The Pacer answers that question directly. It numbers evenly spaced opportunities, called slots, starting at zero. For this application, one slot represents one 188-byte packet.
Here’s a complete Go example:
1package main
2
3import (
4 "fmt"
5 "log"
6 "time"
7
8 "github.com/version2beta/pll"
9)
10
11func main() {
12 rate, err := pll.BitsPerSecond(19_392_000, 188*8)
13 if err != nil {
14 log.Fatal(err)
15 }
16
17 pacer, err := pll.NewPacer(rate)
18 if err != nil {
19 log.Fatal(err)
20 }
21
22 for _, elapsed := range []time.Duration{
23 0,
24 10 * time.Millisecond,
25 25 * time.Millisecond,
26 } {
27 span, err := pacer.Due(elapsed, 4096)
28 if err != nil {
29 log.Fatal(err)
30 }
31
32 fmt.Printf("at %v: %d packets ready\n",
33 elapsed, span.Count)
34
35 if span.Count > 0 {
36 fmt.Printf("first slot: %d, scheduled at %v\n",
37 span.First, span.Time(0))
38 }
39 }
40}This example supplies a few elapsed times rather than actually waiting. In a running sender, the application could pass time.Since(start). Due returns a Span describing consecutive slots that are ready and haven’t already been handed out. The second argument limits how many slots one call can return. Slot zero is ready at time zero. The library doesn’t create packets. The muxer fills those slots and sends the resulting data.
Late execution doesn’t change the schedule
If the application runs late, Due can return several slots together. Each retains its scheduled time. The application chooses what lateness means. A sender might process the backlog. A live preview might discard old work and keep only the newest slots.
The library provides Skip for advancing past overdue slots without handing them out. This doesn’t make delays disappear. If the application consistently processes data more slowly than the requested rate, its backlog will grow. It does remove the requirement to wake once per packet. The program can handle work in batches without rebuilding its schedule around each actual wake-up.
Why not just add an interval?
Go’s time.Duration represents whole nanoseconds. At 19.392 Mbps, the interval between packets is approximately 77,557.76 ns. Rounding that interval to 77,558 ns and repeatedly adding it makes the schedule drift.
The Pacer instead calculates each slot’s time from its number and the exact rate. It rounds only when reporting a timestamp in whole nanoseconds, so that rounding error doesn’t accumulate.
The next article explains how the Go implementation makes those calculations cheap.
Following: interpret incoming timestamps
The outgoing bitrate is a setting I choose. An incoming encoder’s actual timing is something the muxer must estimate.
Encoders have independent clocks, and those clocks can run slightly fast or slow. Network delays also mean that a timestamp’s arrival time isn’t necessarily the time it describes.
The Follower maintains an estimate of the relationship between a source’s counter and local elapsed time. Each observation supplies:
- A local time, measured from the application’s chosen origin.
- A corresponding reading of the source’s counter.
For a PCR clock, the nominal counter rate is 27 million ticks per second. The application extracts and normalizes the counter readings before passing them to the library.2
The main operations are:
Observeupdates the estimate using a pair of local and source readings.Localtranslates a source counter value into estimated local time.Remotetranslates local time into an estimated source counter value.
A phase-locked loop performs the estimation. In broad terms, it predicts a reading, measures the prediction error, and adjusts its estimate of the timing offset and rate. It smooths the observations rather than treating every arrival as equally reliable.
That is where the library’s name comes from. The output schedule itself doesn’t need a feedback loop.
The muxer still owns the decisions
The Follower doesn’t parse transport packets, select programs, rewrite PCR values, or decide where an incoming packet belongs in an outgoing stream. It supplies timing estimates that the muxer can use when making those decisions.
Nor should following an input automatically change the fixed output bitrate. In this project, the output Pacer maintains the configured rate while the input Followers help interpret source timing.
Other applications can connect them differently. A Follower’s rate estimate can trim a Pacer when output should match a device’s actual consumption rate.
Estimates have limits
Delayed readings contain uncertainty. A Follower can filter jitter and reject outliers, but it cannot recover information the observations don’t contain. Reading a recorded file quickly, for example, doesn’t reveal when its packets originally arrived.
Configuration matters too. Observations from a local device and observations crossing a network have different delay patterns; they shouldn’t automatically use the same settings.
If observations stop, the Follower continues using its last rate estimate and exposes a holdover state. That means it is extrapolating, not receiving fresh confirmation.
Other places this is useful
-
Feeding an audio device. A sound card consumes samples using its own clock, which may differ slightly from the advertised rate. If it exposes a consumed-sample counter, a Follower can estimate that rate and trim a Pacer to match, reducing the drift that would otherwise fill or drain the playback buffer.
-
Replaying recorded network traffic. Reading a capture as fast as the disk allows produces a burst rather than a steady stream. For constant-rate replay, a Pacer supplies the schedule while the application chooses whether to catch up or skip overdue slots after a delay.
-
Generating steady test traffic. A network or service test may need evenly scheduled packets or requests rather than a rate limit that permits bursts. A Pacer identifies which sends are ready, letting the application measure whether the sender and target can keep up.
-
Scheduling video frames. Rates such as 30000/1001 frames per second don’t have a whole-nanosecond interval. A Pacer calculates scheduled frame times without accumulated rounding drift, while the application decides whether late frames should be rendered or dropped.
-
Aligning sensor measurements. Sensors can timestamp readings with independent counters that slowly drift apart. Given observations pairing each counter with local time, separate Followers can translate measurements onto a common timeline, with accuracy limited by those observations and their delivery delays.
-
Following a scientific instrument. A digitizer may report a running sample count while delivering measurements in uneven blocks. A Follower can estimate how its sample clock relates to local time, helping timestamp measurements without treating block arrivals as sample times.
-
Replaying simulated device data. A simulator may need to produce thousands of readings per second without sleeping between readings. Because the Pacer accepts time from its caller, a test can advance virtual time and obtain the corresponding slots without waiting for real time to pass.
How the library is checked
The Pacer’s arithmetic has exact answers. Tests compare it with a deliberately simple implementation using arbitrary-precision fractions. Random operation sequences exercise rates, slot numbers, and times near their type limits, as well as ordinary use.
The Follower produces estimates, so it needs two kinds of checks. A model checks that updates follow the specified equations. A deterministic simulator checks accuracy against simulated clocks with drift, jitter, rate changes, jumps, and missing observations.
Those simulations establish behavior under the tested conditions, not every possible device or network. An application still needs tests representative of its own inputs and timing requirements.
Try it
Install the library:
1go get github.com/version2beta/pll@v0.4.0To inspect the implementation and run its checks:
1git clone https://github.com/version2beta/pll.git
2cd pll
3git checkout v0.4.0
4make verify
5make simGive each Pacer or Follower one owner, or protect access with synchronization. Neither is safe for concurrent use; returned Spans are immutable and can be shared.
The useful boundary is straightforward: pll calculates schedules and timing estimates. Your application owns waiting, buffering, sending, and deciding what to do when execution falls behind.
-
ISO/IEC 13818-1, the MPEG-2 systems standard, specifies 188-byte transport-stream packets and a 27 MHz system clock represented by the program clock reference. The permitted clock-frequency tolerance is ±810 Hz, or 30 parts per million. ↩︎
-
MPEG PCR values have a structured representation and wrap around. The application must convert them into the increasing counter readings expected by
Observe, and handle discontinuities appropriately. The Follower operates on counter readings, not MPEG-TS packet formats. ↩︎