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.

By ·9 min read

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:

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:

go
 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:

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:

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

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:

sh
1go get github.com/version2beta/pll@v0.4.0

To inspect the implementation and run its checks:

sh
1git clone https://github.com/version2beta/pll.git
2cd pll
3git checkout v0.4.0
4make verify
5make sim

Give 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.


  1. 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. ↩︎

  2. 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. ↩︎

See also