webrtc_pacer (webrtc v0.1.0)

View Source

Leaky bucket pacer for outgoing media, as a sans-IO engine.

Packets are {Class, Size, Data} with Class one of audio, rtx (retransmissions) or video; Size is the number of bytes on the wire and Data is opaque. The pacer sends at the pacing rate (the rate given to new/1 or set_rate/3, normally pacing_factor times the target bitrate of the congestion controller):

  • The budget grows by rate x elapsed time and is capped at burst_ms worth of the rate (at least one 1500 byte packet), so an idle period never turns into a long burst.
  • A packet leaves while the budget is positive; its size is taken from the budget, which may go negative by at most one packet. Over any interval the bytes sent are at most rate x interval plus the burst cap plus one packet.
  • Audio leaves before retransmissions, which leave before video. Each class is first in, first out.
  • The queue holds at most max_packets. When it is full the oldest video packet is dropped (the incoming one when it is video and no video is queued), then the oldest retransmission, then the oldest audio packet. Drops are counted per class.
  • With max_queue_ms set, the pacer temporarily sends faster when the queue would otherwise take longer than that to drain (as libwebrtc's pacer does), which bounds the queuing delay.

Times are integer milliseconds supplied by the caller.

Summary

Functions

Queue a packet and return the packets that may leave now, in order (possibly including packets queued earlier).

Remove every queued packet, in priority order, without pacing.

Options: rate (bits per second, required), burst_ms (default 10), max_packets (default 1000), max_queue_ms (default infinity).

When the next packet may leave, infinity when the queue is empty.

Change the pacing rate. The budget earned so far is kept.

Types

class/0

-type class() :: audio | rtx | video.

pacer/0

-opaque pacer()

packet/0

-type packet() :: {class(), pos_integer(), term()}.

Functions

enqueue(Pkt, Now, P0)

-spec enqueue(packet(), integer(), pacer()) -> {[packet()], pacer()}.

Queue a packet and return the packets that may leave now, in order (possibly including packets queued earlier).

flush(P)

-spec flush(pacer()) -> {[packet()], pacer()}.

Remove every queued packet, in priority order, without pacing.

handle_timeout(Now, P)

-spec handle_timeout(integer(), pacer()) -> {[packet()], pacer()}.

new(Opts)

-spec new(#{rate := pos_integer(), _ => _}) -> pacer().

Options: rate (bits per second, required), burst_ms (default 10), max_packets (default 1000), max_queue_ms (default infinity).

next_timeout(Pacer)

-spec next_timeout(pacer()) -> integer() | infinity.

When the next packet may leave, infinity when the queue is empty.

queue_length(Pacer)

-spec queue_length(pacer()) -> non_neg_integer().

rate(Pacer)

-spec rate(pacer()) -> pos_integer().

set_rate(Rate, Now, P)

-spec set_rate(pos_integer(), integer(), pacer()) -> pacer().

Change the pacing rate. The budget earned so far is kept.

stats(Pacer)

-spec stats(pacer()) -> map().