nish/term-rate

How fast the link to the terminal is, measured from frames sent and acknowledged, and the frame rate and drawing detail a program keeps to under it.

import {
  BACKEND_CAP_ASCII,
  BACKEND_CAP_HALFBLOCK,
  BACKEND_CAP_KITTY,
  BACKEND_CAP_SIXEL,
  CORNER_BOTTOM_LEFT,
  CORNER_BOTTOM_RIGHT,
  CORNER_TOP_LEFT,
  CORNER_TOP_RIGHT,
  DETAIL_FIRST,
  RATE_FIRST,
  RateController,
  RateDecision,
  RateOptions,
  TermStats,
  drawStatsOverlay,
} from "nish/term-rate";
import { RateController, RateOptions } from "nish/term-rate"

const rate = new RateController(new RateOptions())
// each turn of the loop, at nowMs:
rate.tick(nowMs)
if (rate.mayDraw(nowMs)) {
  // draw as rate.decision() says, then write the frame and `CSI 5 n`
  rate.frameSent(bytes, costNs, nowMs)
}
// for each `CSI 0 n` read back: rate.ackReceived(nowMs)

The module is pure: no capability, no I/O and no clock. The caller feeds a RateController what happened — a frame of so many bytes, costing so many nanoseconds to build, sent at a time; an acknowledgement arriving at a time — and asks it whether a frame may be drawn now and in what shape (RateDecision). Every time is an f64 count of milliseconds on the caller's clock, as FixedStep's is in nish/term.

The acknowledgement

A frame is acknowledged when the terminal answers a status query sent right after it: the terminal answers in order, so the answer means every byte before it has been read and drawn. The query to send is DSR 5, CSI 5 n, answered CSI 0 n.

It is preferred over the cursor position report (DSR 6, CSI 6 n, answered CSI row ; col R) because its answer is one fixed string, and because a cursor report is the same bytes as F3 with modifiers in the legacy key encoding (CSI 1 ; mods R), which a key decoder would have to guess between. Two relays answer the query from their own emulator, not from the terminal at the end of the link:

  • tmux (commit 939e8e65) answers in input.c lines 1737–1747, the INPUT_CSI_DSR case, which replies \033[0n to 5 and the position to 6 through input_reply, whose input_send_reply (lines 1177–1186) writes to the pane. Inside tmux the round trip measures tmux, not the outer terminal, and a frame tmux has taken is not yet on the screen.
  • mosh (commit decd9b70) answers in src/terminal/terminalfunctions.cc lines 471–488, CSI_DSR, which appends the reply to terminal_to_host; src/frontend/mosh-server.cc feeds the program's output to that emulator at line 874 and writes terminal_to_host back to the program at line 882. The answer comes from mosh-server on the remote host and never crosses the network, so mosh reads as a fast local link; its own frame rate limit (mosh sends at most about 50 frames a second) then does the pacing.

Under either relay the controller still bounds the program to what the relay absorbs, which is the most it can know.

What is measured

Four running averages (exponentially weighted, so recent frames count most and none is stored): the round trip from a frame's send to its acknowledgement (weight 1/8, as TCP smooths its round trip, so one late answer moves it little); the bytes a second the link delivered; the cost to build a frame and the bytes in one (weight 1/4 each, so a change of scene shows within a few frames). The bandwidth and the latency are kept apart, so neither can take the other's share of a round trip.

A frame sent before the previous answer, and answered more than the latency after it, kept the link busy from that answer to its own: its bytes over that time measure the bandwidth. A frame sent onto an idle link makes a trip, kept with the last 16 and the probe's: against the quickest kept trip, one twice its bytes or half, 2 ms or more apart, measures the bandwidth from the difference, which the latency is no part of.

Both kinds smooth the bytes and the time apart (weight 1/4 each), so answers arriving in a burst, each taking almost no time, do not read as unbounded bandwidth; answers under 2 ms apart measure nothing this way.

A sample counts for the decisions for 5 seconds with no newer one, so a link that narrows is not held to its old rate; the bandwidth reported keeps it until a newer sample, which starts the average afresh, replaces it, or three trips in a row take over twice what it and the quickest trip kept when it was taken predict.

The figure is at least the most of the last 16 answers' bytes over their whole round trips, since the bytes took no longer than that, so a link that widens shows on its first quick answer; but that bound counts the latency as bytes' time, so alone it never makes the bandwidth known to the decisions.

The base latency is the least, over the kept trips, of the round trip less the trip's bytes at the bandwidth: the probe's round trip (probeRttMs: the status query alone is a few bytes, so its round trip is the latency) counts from the start, the frames' once the bandwidth is known. The kept trips roll over, so a changed route shows within 16 trips.

With frames of one size sent one at a time onto an idle link and no probe the latency and the bytes cannot be told apart: the bandwidth is then not known, its load counts as 0, and the trip load governs on the frame's measured round trip: a cut is taken to shorten none of it and a restore to lengthen all of it, so detail is neither cut for a gain nor restored at a cost that may not be there. Acknowledgements match sent frames oldest first.

A frame due while the unacknowledged limit is reached is dropped and counted; one not answered within rateAckTimeoutMs plus four round trips is given up and counted as lost, so a lost answer stalls drawing for seconds, not for ever. Its answer may still come late, and would otherwise be matched to the next frame, so after a give-up no frame is drawn until as many answers have arrived, or one more timeout has passed without them. A time, cost or size that is not a finite number, or is negative, is not measured, and an empty frame says nothing about bandwidth.

What is decided

The frame rate is a tier: 120 (only with allow120 and a maxFps of 120), 60, 30, 20, 15, 10 or 5. A tier fits when three loads are all at most 1: the frame cost over 70% of the frame time, the bytes a second the tier needs over 70% of the bytes a second the link delivers, and the tier's frames times the round trip over 70% of the time the unacknowledged limit allows (a link that answers in 100 ms carries at most ten frames a second one at a time).

The 30% left over absorbs a slow frame without a dropped one. The rate falls to the best fitting tier after half a second continuously over, and rises one tier after three seconds continuously under the next tier's loads with a fifth to spare; after any change it holds for a second, so the averages see the new rate before the next decision. Falling fast and rising slowly keeps a flickering link from flipping the rate.

It starts at the best tier on a local terminal: the probe answered under 5 ms, or no SSH_* hint and no slow answer. Falling costs half a second and rising one tier costs three, so a terminal that keeps up is never made to climb. A probe that took 5 ms or more starts at 30, and a remote session (the hint, and no fast answer) at 15, as a backlog on a slow link takes far longer to drain than to avoid.

Below the floor tier (the least tier at or above minFps, under RATE_FIRST) the controller cuts bytes instead of frames, one step at a time: half the resolution, a quarter, the backend capped at half blocks, 256 colours. A step is taken only when it would cut the load by a fifth: a link whose round trip is all latency is not helped by smaller frames, so it gets a lower tier at full detail instead. Past the last step, tiers below minFps remain. DETAIL_FIRST swaps the order: every tier down to 5 first, then the steps. Recovery runs the same path backwards with the rising rule, predicting a step's bytes and cost from the factors in rateLevelFactor.

A fixed rate — fixedFps from the program or envFps, the user's NISH_TERM_FPS, which wins — turns the choosing off: the rate is that one, at full detail, and only the unacknowledged limit still applies.

Functions

drawStatsOverlay

Write stats as two short lines, inverse, into corner (a CORNER_*) of screen: the rate, round trip and kilobytes a second, then the frame cost, the frames dropped and the backend cap. A screen too small clips them.

const drawStatsOverlay: (
  screen: Screen,
  stats: TermStats,
  corner: i32,
) => void
screenScreenrequired

The screen to draw on, before it is flushed.

statsTermStatsrequired

What to show, such as RateController.stats().

corneri32required

Which corner, one of the CORNER_ constants.

Classes

RateController

The refresh controller. Each turn of a program's loop: feed it the acknowledgements that arrived (ackReceived), let it re-decide (tick), and draw only when mayDraw says so, reporting the frame with frameSent. decision says how to draw it. decision and stats answer the same object each call, updated in place, so a loop allocates nothing.

class RateController
Member
new RateController(options: RateOptions) A controller for options, read once.
baseRttMs: f64 The link's latency without bytes: the least, over the kept trips, of the round trip less the bytes' time.
bytesPerSec: f64 The bytes a second delivered: ackBytes over ackBusyMs, at least the most of floorPerSec, which alone is a lower bound. Samples older than rateFreshMs still count here while trips agree with them, but no decision uses them.
floorFps: i32 The least tier detail is cut to keep: the floor tier under RATE_FIRST, 5 under DETAIL_FIRST.
haveRate: boolean Whether the bandwidth is known, so decisions may use it: sampled by a frame that waited behind another or two trips of different sizes, within rateFreshMs. The answers' bytes over their round trips are only a lower bound and never make it known.
haveRtt: boolean Whether a round trip, from the probe or an answer, is known.
maxUnacked: i32 How many frames may await their acknowledgement at once: 1 or 2.
prefer: i32 What gives way first, RATE_FIRST or DETAIL_FIRST, from the options.
sentMs: f64[] The send times of the unacknowledged frames, oldest at head.
tripMs: f64[] The round trips of the probe and of the latest frames sent onto an idle link, rateTripCount at most.
ackReceived(nowMs: f64): void An acknowledgement arrived at nowMs; it answers the oldest frame not yet answered. While frames given up on may still be answered, it is theirs, since the terminal answers in order. One with no frame waiting (a stray answer) is ignored, and one whose time is not a finite number answers its frame and measures nothing.
decision(): RateDecision How to draw the next frame, as of the last tick.
frameSent(bytes: i32, costNs: f64, nowMs: f64): void A frame of bytes bytes, which took costNs nanoseconds to build, was sent at nowMs. A call whose time is not a finite number is ignored; a cost that is not a finite number or is negative is not measured, and negative bytes count as none.
mayDraw(nowMs: f64): boolean Whether a frame may be drawn at nowMs: one is due at the tier's pace and fewer than maxUnacked frames await their acknowledgement. The first call starts the pace and answers a frame at once. A due frame refused for the limit, or while the answers to frames given up on may still come, is counted as dropped, and the next waits for the next step. A time that is not a finite number is refused.
stats(): TermStats What has been measured, as of the last tick.
tick(nowMs: f64): void Re-decide at nowMs: give up frames long unanswered, then fall, cut detail, restore it or rise, at most one change, with the hysteresis the module header describes. Nothing is decided before the first acknowledgement, nor at a fixed rate.
unacked(): i32 Frames sent and not yet acknowledged.

RateDecision

How to draw the next frame: its rate and how much detail.

class RateDecision
Member
new RateDecision() Full detail at 30 frames a second, until the controller says otherwise.
backendCap: i32 The richest backend to draw with, a BACKEND_CAP_*.
fps: i32 Frames a second.
palette256: boolean Whether to keep to the 256-colour palette.
resolutionDivisor: i32 Draw at the screen's resolution divided by this: 1, 2 or 4.

RateOptions

What a program asks of the controller. Every field has a default, so a program sets only what it means.

class RateOptions
Member
new RateOptions() The defaults; set the fields to change them.
allow120: boolean Whether the 120 tier may be used, for a terminal known to keep up with it.
envFps: i32 The user's NISH_TERM_FPS, which fixes the rate over everything else; 0 when unset.
fixedFps: i32 A frame rate the program fixes, turning the choosing off; 0 leaves it on.
maxFps: i32 The most frames a second; 120 is reached only with allow120 as well.
maxUnacked: i32 How many frames may be awaiting their acknowledgement at once: 1 or 2.
minFps: i32 The least frame rate worth keeping before detail is cut, under RATE_FIRST.
prefer: i32 RATE_FIRST or DETAIL_FIRST: what gives way first when even minFps does not fit.
probeRttMs: f64 The round trip of a probe query sent at startup, in milliseconds; 0 when none was measured.
remoteHint: boolean Whether the environment says the terminal is remote (an SSH_* variable, say).

TermStats

What the controller has measured, for a program to show or log.

class TermStats
Member
new TermStats() Nothing measured yet.
backend: i32 The backend cap in force, a BACKEND_CAP_*.
bytesPerSec: f64 The smoothed bytes a second the link delivers.
dropped: i32 Due frames skipped because the unacknowledged limit was reached.
frameCostMs: f64 The smoothed cost to build a frame, in milliseconds.
lost: i32 Frames given up on after waiting rateAckTimeoutMs past four round trips.
rttMs: f64 The smoothed round trip from a frame's send to its acknowledgement, in milliseconds.
tier: i32 The frame rate in force.
unacked: i32 Frames sent and not yet acknowledged.

Constants

0

BACKEND_CAP_ASCII: i32

RateDecision.backendCap and TermStats.backend: the richest drawing backend allowed. The values order the backends, richer higher, so a caller takes the lesser of this and what the terminal supports.

1

BACKEND_CAP_HALFBLOCK: i32

A backend cap of Unicode half blocks, two pixels to a cell.

3

BACKEND_CAP_KITTY: i32

A backend cap of the kitty graphics protocol, the richest: no cap at all.

2

BACKEND_CAP_SIXEL: i32

A backend cap of sixel graphics.

2

CORNER_BOTTOM_LEFT: i32

The bottom left corner.

3

CORNER_BOTTOM_RIGHT: i32

The bottom right corner.

0

CORNER_TOP_LEFT: i32

drawStatsOverlay's corner: the top left.

1

CORNER_TOP_RIGHT: i32

The top right corner.

1

DETAIL_FIRST: i32

RateOptions.prefer: keep full detail and drop the frame rate toward 5 first.

0

RATE_FIRST: i32

RateOptions.prefer: keep the frame rate at minFps and cut detail first.