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)
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.
RateController
The refresh controller.
RateDecision
How to draw the next frame: its rate and how much detail.
RateOptions
What a program asks of the controller.
TermStats
What the controller has measured, for a program to show or log.
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.clines 1737–1747, theINPUT_CSI_DSRcase, which replies\033[0nto 5 and the position to 6 throughinput_reply, whoseinput_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.cclines 471–488,CSI_DSR, which appends the reply toterminal_to_host;src/frontend/mosh-server.ccfeeds the program's output to that emulator at line 874 and writesterminal_to_hostback 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
screenScreenrequiredThe screen to draw on, before it is flushed.
statsTermStatsrequiredWhat to show, such as RateController.stats().
corneri32requiredWhich 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.

