Documentation
¶
Overview ¶
Package timing holds every stall window this repository's tests turn on, and the evidence behind each one.
Why the windows live here rather than beside the rows they govern ¶
A stall window is a MARGIN, and a margin is only as good as the measurement it was sized from. Written inline, a window is a number in a test file: the next reader sees the value and not the quantity it bounds, the machine it was measured on, or whether it was measured at all. Five of these existed in two files, and exactly one of them had a measurement behind it — the other four were numbers somebody chose, and one of those four was sized against the fixture's own pacing knob, which is the quantity the row does NOT depend on.
A constant carried between two places carries its number, not the reason the number was chosen. So the number and the reason are stored together, and a guard beside this package refuses a stall window that is not here.
Not internal/testing ¶
A package of that name sitting beside the standard library's `testing` is a confusion nobody needs, and this one is about time rather than about tests.
How the numbers in here were taken ¶
Each leg's number is the worst gap seen across CONSECUTIVE runs of that entry's probe, and the count is a FLOOR of twenty with the actual figure written into the entry. Twenty is the least that can be called a distribution; more is better, and where more were done the record says how many, because a reader weighing a margin needs to know whether it stands on the floor or well above it. See MinimumRuns — this paragraph used to say a hundred, flatly, while the task that wrote it asked for twenty, and the two disagreed for a day.
A pass with the whole suite running in parallel is worth more than one on an idle machine, because a margin measured on an idle machine is not the margin a gate has. The probes live beside the rows they measure, in internal/flow, and reproduce each row's own fixture rather than a cheaper approximation of it: a shorter transfer over a connection kept warm answered a different question by 160 ms.
A block point is likewise the LARGEST seen, because the danger it guards against is a fixture too small to make the client block, and the largest block point is the one a fixture has to clear.
A WRITE-SIDE NUMBER IS ALSO TAKEN UNDER A PIN ¶
The gap a write-side window bounds is set by socket buffers at BOTH ends of the connection, and both kernels grow those as a connection carries traffic. So the write-side probes pin them — the client's SO_SNDBUF through a dialler, the fixture's SO_RCVBUF on every connection it accepts — and read each one back with getsockopt, because setsockopt may clamp, round, double or ignore a request and says so nowhere. The pin is recorded beside the gap, per leg, and it is part of the number: a run whose sockets read back a different size is not a run that beat the record, it is a run under a different condition, and the rows say so rather than comparing the two figures.
What the pin buys was measured rather than assumed. On darwin, one probe, one pass of twenty runs at each size: 37.7 ms at 16 KiB, 107.8 ms at 64 KiB, 110-122 ms at 128 KiB, 139.5 ms at 512 KiB, and 417.9-434.1 ms with no pin at all. The curve saturates above about 64 KiB, where what is left is the fixture's own pacing quantum and the scheduler; below it the buffer is the whole quantity.
128 KiB IS WHAT THIS REPOSITORY ASKS FOR, AND IT IS NOT WHAT THE CURVE PREFERS. The table above is one leg's, and a second leg overruled it: at 16 KiB the hosted linux runner stopped finishing the upload probe at all, where 128 KiB completes it in about thirty seconds there. A leg that reports nothing is worse than a leg that reports a wider margin, so the size is the one with evidence on all three legs rather than the one with the best number on one of them. The reasoning, and the two hypotheses that were killed before it was accepted, are at pinnedBuffer in internal/flow.
AND ON DARWIN ONLY ONE OF THE TWO ENDS STAYS WHERE IT IS PUT ¶
A read-back is an INSTANT. Sampled repeatedly while a body was actually moving — which is what Pin.Sustained records — the client's SO_SNDBUF held at the requested 131,072 bytes across every one of 16,653 samples, and the accepting end's SO_RCVBUF read back 131,072 and was then run by the kernel up to 646,336 across 16,649. macOS ships net.inet.tcp.doautorcvbuf=1 and setting SO_RCVBUF does not clear it; re-setting the option on every drain step held the floor and not the ceiling.
So on this leg the pair is one pinned end and one that is merely asked, and that is what the entry records: send pinned and confirmed, receive UNPINNABLE, with the range the kernel ran it over while the body moved written down beside the gap. It is a disclosed condition rather than a claimed one.
WHAT EACH END IS WORTH IS A PER-LEG QUESTION AND IS MEASURED AS ONE ¶
There is no general sentence here about which end governs. A control in internal/flow holds the send end still and varies only the receive end, and its tables are recorded beside the pin, per leg, because a claim about three legs made from one leg's arithmetic is precisely what this package exists to stop. Each leg's window comes from that leg's own measurement, under that leg's own recorded condition.
This package is imported by test files only ¶
It compiles as ordinary code so that a test in any package can import it, and nothing outside a _test.go file does — which is asserted rather than hoped for, so no registry of test margins reaches a shipped binary.
Index ¶
Constants ¶
const MinimumMargin = 5
MinimumMargin is the sizing rule, and it lives at the registry because this is where the numbers are.
A window is at least FIVE TIMES the measured worst gap on the SLOWEST leg — not the average, and not the machine the author happens to be sitting at. The margin that failed one run in six was twelve times the fixture's own pacing knob and about twice the quantity the row actually depended on; a multiple of the governing quantity is the only multiple that means anything.
const MinimumRuns = 20
MinimumRuns is the FLOOR on the run count behind a leg's number, and it is a floor rather than a target.
One run is an outcome; a margin is a distribution. The window that preceded the first measured one here failed about one run in six and passed the single run that chose it, which is the whole argument for a number rather than a habit. Twenty is the least that can be called a distribution at this scale.
THE RECORD STATES THE ACTUAL COUNT, not this constant. A hundred runs are recorded as a hundred, because a reader weighing a margin needs to know whether it stands on the floor or well above it — and because a record that rounded every count down to the minimum would make five passes and one pass indistinguishable. This package's own doc comment used to say a hundred, flatly, while the task that wrote it asked for twenty; the two disagreed for a day and a reader had no way to tell which described the entry in front of them.
Variables ¶
var Bounds = map[string]*Bound{ "Connect": &Connect, "TLSHandshake": &TLSHandshake, "ResponseHeaders": &ResponseHeaders, }
Bounds is every connection bound, by name.
var Ceilings = map[string]*Ceiling{ "TokeniserCost": &TokeniserCost, }
Ceilings is every ceiling a test asserts. A ceiling declared and not listed here is one the guard cannot see, and it reds on that.
var Connect = Bound{ Name: "Connect", Value: api.DefaultConnectTimeout, Governs: "dialling the server, from the request leaving to the TCP connection being established", Reason: "provisional, ruled 2026-09-29 as a starting point: long enough for a slow or " + "distant network to connect, short enough that a host that will never answer is " + "reported as unreachable rather than left hanging. Not yet measured; re-ruled from " + "measurement.", Provisional: true, }
Connect bounds establishing the TCP connection.
var Legs = []Leg{Linux, Darwin, Windows}
Legs is every leg an entry must carry a measurement for. It is the set the gate runs, and a window measured on fewer of them is a window whose margin is unknown where it is not measured.
var Registry = map[string]*Entry{ "UploadSlowIsNotStalled": &UploadSlowIsNotStalled, "UploadWedgedStops": &UploadWedgedStops, "StreamGoesQuiet": &StreamGoesQuiet, "StreamKeepAlivesAreProofOfLife": &StreamKeepAlivesAreProofOfLife, "StreamPartialLineIsNotAStall": &StreamPartialLineIsNotAStall, }
Registry is every stall window in this repository, keyed by name.
It is written out rather than assembled by reflection, so that adding an entry is a deliberate, readable act — and the row beside it walks this package's own source to prove no declared entry is missing from here, because a registry that can be silently under-populated is not one.
var ResponseHeaders = Bound{ Name: "ResponseHeaders", Value: api.DefaultResponseHeaderTimeout, Governs: "the server answering, from the request being written to its response headers arriving", Reason: "provisional, ruled 2026-09-29 as a starting point, equal to the client's existing " + "per-request total so no ordinary call is bounded more tightly than before. For the " + "build log it is the bound on a server that accepts and never answers, which the " + "stall window covered only while it was armed before the connection opened. Not yet " + "measured; re-ruled from measurement.", Provisional: true, }
ResponseHeaders bounds the wait for the server's response headers once the request has been written.
var StreamGoesQuiet = Entry{ Name: "StreamGoesQuiet", Row: "TestAStreamThatStopsTalkingIsReconnected", Window: 100 * time.Millisecond, Side: Read, Governs: "the interval from the watchdog being armed — on the response arriving — " + "to the first byte of the first frame arriving: delivery plus whatever the " + "scheduler adds. Measured under the earlier arming, when it also covered " + "connection establishment; re-measured under this one before the window moves", Instrument: "streamProgress, internal/flow/stream.go", Pace: &FixturePace{Interval: 0, Flushes: 2}, Measurements: map[Leg]Measurement{ Linux: {WorstGap: 410607 * time.Nanosecond, Runs: 1000, Date: "2026-09-29", FlushBudget: 203517 * time.Nanosecond, Integrity: &PaceIntegrity{Attempts: 1000, Valid: 1000, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 0, FlushBudget: 203517, Flushes: 2, WorstFixtureGap: 122196, ValidGapMin: 17312, ValidGapMedian: 21981, ValidGapMax: 122196}}, Darwin: {WorstGap: 19935917 * time.Nanosecond, Runs: 1000, Date: "2026-09-29", FlushBudget: 11010375 * time.Nanosecond, Integrity: &PaceIntegrity{Attempts: 1000, Valid: 1000, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 0, FlushBudget: 11010375, Flushes: 2, WorstFixtureGap: 10072417, ValidGapMin: 9042, ValidGapMedian: 18708, ValidGapMax: 10072417}}, Windows: {WorstGap: 2045400 * time.Nanosecond, Runs: 1000, Date: "2026-09-29", FlushBudget: 2133200 * time.Nanosecond, Integrity: &PaceIntegrity{Attempts: 1000, Valid: 1000, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 0, FlushBudget: 2133200, Flushes: 2, WorstFixtureGap: 2094300, ValidGapMin: 0, ValidGapMedian: 0, ValidGapMax: 2094300}}, }, SetBy: Darwin, }
StreamGoesQuiet bounds the row that proves a stream which stops talking is picked up again. The fixture sends one frame and then holds the connection open, sending nothing.
ITS GOVERNING QUANTITY IS NOT THE OTHER TWO STREAM ROWS'. The window has to outlast the gap from the watchdog being armed — on the response arriving — to the first byte of the first frame, which is delivery and scheduling. Nothing paces this fixture, so there is no inter-frame gap to measure. Connecting and the wait for the response are no longer in it: each has its own bound on the transport.
MEASURED UNDER THE EARLIER ARMING. Until the build-log reader armed its watchdog on the response, it armed it before the connection was opened, and every measurement and window in this entry was taken that way. They stand as they are until the entry is re-measured under the current arming, and no window here is re-sized before then.
A SECOND ROW TAKES THIS WINDOW, and it is recorded here rather than only at the row, because a reader of this entry would otherwise think it bounds one thing. TestASilentStreamEndsTheReadingRatherThanWaiting covers the status read of a stream that has gone silent: a different caller, the same quantity — the watchdog is armed on the response, the fixture delivers and then holds, and the instrument named below is the one both readings are wrapped in. The measurement is carried with that reason rather than re-taken, which is what this registry permits and what it forbids doing silently.
var StreamKeepAlivesAreProofOfLife = Entry{ Name: "StreamKeepAlivesAreProofOfLife", Row: "TestKeepAliveFramesAreProofOfLifeAndAreNeverRendered", Window: 245 * time.Millisecond, Side: Read, Governs: "the interval between two flushes ARRIVING at this client at the " + "fixture's keep-alive pace — the pace plus delivery plus scheduling, not " + "the pace on its own; the first such interval runs from the watchdog " + "being armed, which is on the response arriving. Measured under the " + "earlier arming, before the connection was opened; re-measured under " + "this one before the window moves", Instrument: "streamProgress, internal/flow/stream.go", Pace: &FixturePace{Interval: 15 * time.Millisecond, Flushes: 36}, Measurements: map[Leg]Measurement{ Linux: {WorstGap: 16073012 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 15000000, FlushBudget: 0, Flushes: 36, WorstFixtureGap: 16094983, ValidGapMin: 15299298, ValidGapMedian: 15531604, ValidGapMax: 16094983}}, Darwin: {WorstGap: 48725708 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 21, Valid: 20, Starved: 1, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 15000000, FlushBudget: 0, Flushes: 36, WorstFixtureGap: 66403291, ValidGapMin: 17365209, ValidGapMedian: 22587500, ValidGapMax: 34800125}}, Windows: {WorstGap: 26585800 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 15000000, FlushBudget: 0, Flushes: 36, WorstFixtureGap: 23318200, ValidGapMin: 15824900, ValidGapMedian: 16044600, ValidGapMax: 23318200}}, }, SetBy: Darwin, }
StreamKeepAlivesAreProofOfLife bounds the row that proves a comment frame counts as traffic. The fixture sends nothing but keep-alives, paced, for longer than the window.
var StreamPartialLineIsNotAStall = Entry{ Name: "StreamPartialLineIsNotAStall", Row: "TestBytesArrivingWithoutANewlineAreNotAStall", Window: 285 * time.Millisecond, Side: Read, Governs: "the interval between two partial writes of one frame ARRIVING at this " + "client at the fixture's own pace — the pace plus delivery plus scheduling; " + "the first such interval runs from the watchdog being armed, which is " + "on the response arriving. Measured under the earlier arming, before the " + "connection was opened; re-measured under this one before the window moves", Instrument: "streamProgress, internal/flow/stream.go", Pace: &FixturePace{Interval: 20 * time.Millisecond, Flushes: 61}, Measurements: map[Leg]Measurement{ Linux: {WorstGap: 20926714 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 20000000, FlushBudget: 0, Flushes: 61, WorstFixtureGap: 20797129, ValidGapMin: 20377575, ValidGapMedian: 20411270, ValidGapMax: 20797129}}, Darwin: {WorstGap: 56283875 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 22, Valid: 20, Starved: 2, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 20000000, FlushBudget: 0, Flushes: 61, WorstFixtureGap: 82407875, ValidGapMin: 22525708, ValidGapMedian: 26962334, ValidGapMax: 55886292}}, Windows: {WorstGap: 23188400 * time.Nanosecond, Runs: 20, Date: "2026-09-29", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 20000000, FlushBudget: 0, Flushes: 61, WorstFixtureGap: 23188400, ValidGapMin: 20814800, ValidGapMedian: 20955700, ValidGapMax: 23188400}}, }, SetBy: Darwin, }
StreamPartialLineIsNotAStall bounds the row that proves bytes arriving without a newline are progress. The fixture delivers one frame in a long sequence of paced one-byte pieces.
IT IS NOT CARRIED FROM THE KEEP-ALIVE ROW even though both are read side through the same reader, because the two fixtures pace differently and the gap being bounded includes that pace. A measurement taken at one pace does not bound a row running at a slower one, and carrying it would be the defect this package exists against wearing a permitted name.
THIS WINDOW IS THE INSTANCE BEHIND THE RULE AT FixturePace ¶
It has been 60 ms, then 150, then 250, then 350, then 400 — the last three inside a single round, each one arrived at by applying the five-times rule correctly to a fresh measurement. Sixty was three times the fixture's own pacing knob, the visible quantity rather than the governing one, and that was the defect everyone knew about. The three that followed were something else: the fixture's LENGTH was computed from the window, so a wider window delivered for longer, a longer delivery sampled more of a heavy tail, and the larger maximum asked for a wider window again.
AN INSTRUMENT THAT FOLLOWS ITS OWN READING CANNOT CONVERGE, and no amount of care at any one step of that loop would have shown it. What shows it is the sequence.
So the fixture is a STATED CONSTANT — see partialLineDelivery and partialLinePace in internal/flow — and the window is five times the maximum measured under it. The row still asserts it spent three windows on one line, and it now CHECKS that the stated fixture is long enough to do so rather than growing one that is: a window past what the constant can cover is a red that asks a person to raise the constant deliberately, which is the same decision as before with the feedback loop taken out of it.
The helper still grows the line and CHECKS what it got rather than computing a count and trusting it — splitEvenly rounds the piece size up and then runs out of string, so a computed count of forty-three silently produced thirty.
var TLSHandshake = Bound{ Name: "TLSHandshake", Value: api.DefaultTLSHandshakeTimeout, Governs: "the TLS handshake, from the connection being established to the secure channel being ready", Reason: "provisional, ruled 2026-09-29 as a starting point, and the figure the standard " + "library's own default transport uses. A custom transport does not inherit it, so " + "until it was set this phase had no bound at all. Not yet measured; re-ruled from " + "measurement.", Provisional: true, }
TLSHandshake bounds the TLS handshake once the connection is up.
var TokeniserCost = Ceiling{ Name: "TokeniserCost", Row: "TestTheCostOfTokenisingIsBoundedByTheBound", Governs: "the best-of-seven cost of tokenising a line of alternating case " + "four times as long, over the cost of the shorter line", Value: 16, Provisional: true, ReRuleAfter: 20, Why: "sized on one development machine (bounded ratios 4.0 to 4.2 over ten " + "trials, unbounded 56); no reading from a hosted runner", }
TokeniserCost bounds how much longer the identifier tokeniser takes on an input four times the size, on the worst input it has.
var UploadSlowIsNotStalled = Entry{ Name: "UploadSlowIsNotStalled", Row: "TestASlowUploadIsNotAStalledOne", Window: 900 * time.Millisecond, Side: Write, Governs: "the time for the kernel's send buffer to free space, which is set by how " + "fast the far end reads and by how much window it advertises at a time — not " + "by the pause the store fixture asks for, and a fixed quantity at all only " + "while both ends' buffers are pinned", Instrument: "progressReader, internal/flow/upload.go", Measurements: map[Leg]Measurement{ Darwin: { WorstGap: 179409167 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 57369375, ValidGapMin: 26486875, ValidGapMedian: 26716750, ValidGapMax: 57369375}, BlockPoint: 819200, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 16653, Low: 131072, High: 131072}}, Receive: Pin{Requested: 131072, Err: "this kernel's own receive autosizing moves an accepted socket's " + "buffer whatever SO_RCVBUF asked for: sampling during a body found " + "it between 131072 and 646336, and two connections in one run can " + "read back different sizes", Sustained: &Sustained{Samples: 16649, Low: 131072, High: 646336}}, }, }, Linux: { WorstGap: 102256000 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 26301870, ValidGapMin: 25833365, ValidGapMedian: 25947440, ValidGapMax: 26301870}, BlockPoint: 589824, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 262144, Sustained: &Sustained{Samples: 2299, Low: 262144, High: 262144}}, Receive: Pin{Requested: 131072, ReadBack: 262144, Sustained: &Sustained{Samples: 2299, Low: 262144, High: 262144}}, }, }, Windows: { WorstGap: 53542000 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 27003200, ValidGapMin: 25819200, ValidGapMedian: 26065400, ValidGapMax: 27003200}, BlockPoint: 229376, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 2327, Low: 131072, High: 131072}}, Receive: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 2327, Low: 131072, High: 131072}}, }, }, }, SetBy: Darwin, }
UploadSlowIsNotStalled bounds the row that proves a slow upload is not a stalled one: the store consumes the body at a pace that makes the whole upload span several windows while never letting the gap between two bytes reach one.
WHAT THE NUMBER IS, AND WHAT IT IS A NUMBER ABOUT ¶
226.326875 ms, the worst gap over 240 consecutive runs on darwin — twelve passes of twenty on 2026-09-11, all of them with the whole package running, all of them under the race detector. A 1150 ms window is 5.08 times it.
IT WAS 126.162 ms OVER 140 RUNS AND THAT NUMBER WAS NOT WRONG, it was short. Seven passes agreed with each other to within six per cent and twelve found a range of 109 to 226. See the darwin measurement below for the readings, for the idle-versus-busy control that failed to find an axis for the spread, and for what is still open about it.
The condition is named because a gap is only that number under one: both ends asked for a 131,072-byte socket buffer, the client's held there for every sample taken while a body was moving, and the store fixture's was moved by the kernel up to 646,336 — see the package comment, and Pin.Sustained. Every connection is fresh: the row opens one, and a connection kept warm across runs answered a different question by 160 ms when round 1 tried it.
THE ROUND BEFORE THIS ONE MEASURED THROUGH A HOLE IN ITS OWN INSTRUMENT ¶
Round 2 recorded 154.359 ms here under a 128 KiB pin, and struck it. The receive-buffer size was a field written onto the store fixture AFTER its listener had started accepting, so a connection could be accepted before the size existed; under the race detector the write and the accept-path read were reported as the data race they were, and the round's own "two connections in one run disagree" refusal reported the consequence — 392,384 on one connection and 131,072 on the next, with a worst gap of 267.2 ms against a recorded 154.4 ms. Nothing from that round carried across the fix. The pin is now a PARAMETER of the fixture's constructor and the listener is wrapped with it already in place, which is why there is no longer anything for a mutex to guard.
THE NUMBER IS TAKEN UNDER THE RACE DETECTOR BECAUSE THE ROW RUNS THERE ¶
make ci runs this package twice, once plainly and once under -race, so the detector is one of the conditions this margin has to hold in. It is the worse one: the same probe reported 42.1 ms without it. A margin sized against the friendlier of two conditions the gate actually uses is a margin that is right in the runs nobody worries about.
AND THE FIXTURE FOLLOWS THE WINDOW RATHER THAN SITTING BESIDE IT ¶
The three-window assertion costs paced bytes in proportion to the window, so the row derives its fixture from this number rather than carrying constants that agree with it only on the leg they were typed on. See pacingFor in internal/flow.
THE CEILING IS TWENTY SECONDS, AND IT INCLUDES THE RACE PASS ¶
It was fifteen, and fifteen was chosen while the gate ran these rows once. The gate now runs them TWICE — plainly and under the race detector — and the detector is not a rounding error here.
RETAKEN 2026-09-11, on the tip this ceiling describes, after the window went 800 ms to 1150: the two rows cost 10.02 s and 7.23 s under the detector against 4.55 s and 1.91 s without. SEVENTEEN POINT TWO FIVE SECONDS COMBINED under the detector, six point four six without.
THAT IS 2.75 s OF HEADROOM AND IT IS THE THINNEST THIS CEILING HAS BEEN. At the 800 ms window the same pair cost 13.24 s under the detector (7.46 and 5.78, against 3.16 and 1.51 without), and a second measurement that day gave 13.75 s. The fixture spans three and a half windows by construction, so this cost rises with the window roughly in proportion: another move of the size the last one was would put the pair through the ceiling. Whether the ceiling then moves or the rows change shape is a ruling, and it is one worth having before the number forces it rather than after.
So the ceiling restates rather than moves: it is the same intent — the live suite's timeout has to exceed its row budgets, and that is a number to see rather than to discover — applied to the condition the gate actually runs. A ceiling that excluded the detector pass would be a budget for a run nobody makes, and the number it reported would be the friendlier of two figures with nothing beside it saying which.
var UploadWedgedStops = Entry{ Name: "UploadWedgedStops", Row: "TestAWedgedUploadStopsAndSaysSo", Window: 900 * time.Millisecond, Side: Write, Governs: "the time for the kernel's send buffer to free space, which is set by how " + "fast the far end reads — the same quantity its sibling row measures, under " + "the same pin", Instrument: "progressReader, internal/flow/upload.go", Measurements: map[Leg]Measurement{ Darwin: { WorstGap: 179409167 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 57369375, ValidGapMin: 26486875, ValidGapMedian: 26716750, ValidGapMax: 57369375}, BlockPoint: 819200, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 16653, Low: 131072, High: 131072}}, Receive: Pin{Requested: 131072, Err: "this kernel's own receive autosizing moves an accepted socket's " + "buffer whatever SO_RCVBUF asked for: sampling during a body found " + "it between 131072 and 646336, and two connections in one run can " + "read back different sizes", Sustained: &Sustained{Samples: 16649, Low: 131072, High: 646336}}, }, }, Linux: { WorstGap: 102256000 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 26301870, ValidGapMin: 25833365, ValidGapMedian: 25947440, ValidGapMax: 26301870}, BlockPoint: 589824, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 262144, Sustained: &Sustained{Samples: 2299, Low: 262144, High: 262144}}, Receive: Pin{Requested: 131072, ReadBack: 262144, Sustained: &Sustained{Samples: 2299, Low: 262144, High: 262144}}, }, }, Windows: { WorstGap: 53542000 * time.Nanosecond, Runs: 20, Date: "2026-09-11", Integrity: &PaceIntegrity{Attempts: 20, Valid: 20, Starved: 0, ThresholdNum: 3, ThresholdDen: 1, StatedPace: 25 * time.Millisecond, WorstFixtureGap: 27003200, ValidGapMin: 25819200, ValidGapMedian: 26065400, ValidGapMax: 27003200}, BlockPoint: 229376, Pin: &PinnedPair{ Send: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 2327, Low: 131072, High: 131072}}, Receive: Pin{Requested: 131072, ReadBack: 131072, Sustained: &Sustained{Samples: 2327, Low: 131072, High: 131072}}, }, }, }, SetBy: Darwin, Carried: &Carried{ From: "UploadSlowIsNotStalled", Reason: "the two rows are one ruling and share one window by construction: a " + "single number has to let a slow upload through and stop a wedged one, " + "so a window that differed between them would prove neither half. Same " + "side (write), same reader (progressReader), same store fixture, and the " + "gap being bounded is the same send-buffer drain — the wedged row simply " + "stops the drain rather than slowing it. Both rows also run under the " + "same pinned pair of socket buffers, which is what makes the shared " + "number a shared CONDITION rather than a shared digit.", }, }
UploadWedgedStops bounds the other half of that pair: a store that reads a little and then stops reading at all, holding the request open. One window has to let the slow upload through and stop this one, so the two numbers are the same number by construction.
THE PIN IS CARRIED WITH THE NUMBER, and it has to be. A window is five times a gap only under the condition the gap was measured in, so a wedged row running over an autotuned socket while its sibling ran over a pinned one would be two rows depending on one constant while standing in two different environments. Its row pins both ends the same way; see internal/flow/socketpin_test.go.
Functions ¶
This section is empty.
Types ¶
type Bound ¶ added in v0.1.6
type Bound struct {
// Name must equal the key the bound is registered under and the
// identifier it is declared as.
Name string
// Value is the bound itself.
Value time.Duration
// Governs names the interval the bound ends, stated as the phase of a
// request rather than as the knob that sets it.
Governs string
// Reason is why this number and not another. For a provisional bound
// it says so and says what it rests on.
Reason string
// Provisional is true until the bound is re-ruled from a measurement.
Provisional bool
}
Bound is a limit the shipped client enforces on one phase of opening a connection: how long it waits to connect, to finish the TLS handshake, or for the server's response headers.
Why these live beside the stall windows ¶
The build log is read in phases, and each phase has exactly one named bound. A stall window bounds a silence once the response has arrived; these three bound everything before it. They are recorded here, with the reason each number was chosen, for the reason the windows are: a constant carried to the place that uses it carries its number and not the reason, and a number nobody can trace is a number nobody can move.
They are not windows, and the registry treats them apart ¶
An Entry is a margin over a measured gap, and it is refused without a measurement on every leg. None of these has been measured: they were ruled as starting points, and each says so. They become measurements the way the windows did, and until then Provisional stays true and the guard beside this file requires the reason to say what they rest on.
The numbers are the client's, and this is their record ¶
Unlike the windows, these values are SHIPPED: the client's transport enforces them. This registry is kept out of the shipped binary, because it names test rows and carries measurement provenance nobody who downloads the client should find inside it. So the numbers live as the client's own constants, and each Bound here READS its constant rather than restating it: one home per number, and the reason beside it here.
type Carried ¶
type Carried struct {
// From is the Name of the entry the numbers came from.
From string
// Reason is why the measurement transfers: the same side, the same
// reader, and what makes the two rows one mechanism. "The same as X"
// is a citation of a reason that was about something else, so a
// reason that says only that is no reason.
Reason string
}
Carried records that an entry's measurement came from another entry rather than from a run of its own.
CARRYING IS ALLOWED WITH ITS REASON, and only with it. Rows sharing a mechanism may share a measurement — the argument for why it transfers is how a measurement is meant to be used. Carrying the number alone is the defect this whole package exists against, so an entry that names a source and gives no reason is refused.
type Ceiling ¶
type Ceiling struct {
// Name is the identifier, the Ceilings key and this field: one name.
Name string
// Row is the test that asserts the ceiling.
Row string
// Governs says in words what the ratio is a ratio of.
Governs string
// Value is the ceiling. A measured ratio above it fails the row.
Value float64
// Provisional says no hosted reading stands behind Value: it is a
// number chosen somewhere other than where it is enforced.
Provisional bool
// ReRuleAfter is how many hosted readings PER LEG re-rule a
// provisional ceiling. Zero is nobody having said when it stops being
// provisional, and the guard reds on it.
ReRuleAfter int
// Why is what a provisional value was sized from, so a reader can see
// how little stands behind it.
Why string
}
Ceiling is a bound on a RATIO a test measures, where an Entry bounds a DURATION. It lives in this package for the reason an Entry does: a number a row asserts against is a claim about machines, and a claim about machines is recorded with what stands behind it.
A CEILING HAS NO FIELD FOR READINGS, and that is deliberate rather than unfinished. No ceiling in the tree has been read on a hosted runner, so every one of them is PROVISIONAL, and the guard beside this package refuses a ceiling that says otherwise. Re-ruling a ceiling from its hosted readings is the change that adds the field those readings go in.
type Entry ¶
type Entry struct {
// Name is this entry's own name, and it must equal the key it is
// registered under and the identifier it is declared as. The guard
// resolves a test's `timing.Name.Window` to this.
Name string
// Row is the test this window governs, named so a reader of the
// registry can go and read the row, and a reader of the row can find
// the evidence.
Row string
// Window is the stall window itself.
Window time.Duration
// Side is which mechanism this window bounds.
Side Side
// Governs names the quantity the gap is actually set by — not the
// knob the fixture turns. Sizing a window against the visible
// quantity rather than the governing one is how a timing row becomes
// a flake with a schedule.
Governs string
// Instrument is the progress reader the measurement is taken
// through. A measurement may only be carried between rows on the
// same side, through the same reader.
Instrument string
// Pace is the fixture's stated pacing, and it is READ SIDE ONLY for
// the same reason Pin and BlockPoint are write side only: it is the
// condition that side's gap is measured under, and the other side
// has a different one. A read-side entry with no Pace is nobody
// saying, and the guard reds on it; a write-side entry carrying one
// is a condition with no bearing on the number beside it, and the
// guard reds on that too.
Pace *FixturePace
// Measurements is the per-leg evidence. A leg absent from this map,
// or present with a zero Measurement, is UNMEASURED and the guard
// reds on it.
Measurements map[Leg]Measurement
// SetBy is the leg whose number sized this window: the slowest of
// the measured legs. It is checked rather than decorative — an entry
// naming a leg that is not its slowest is refused.
SetBy Leg
// Carried is non-nil when this entry's numbers came from another
// entry rather than from its own run.
Carried *Carried
}
Entry is one stall window and everything known about it.
func (*Entry) SlowestMeasuredLeg ¶
SlowestMeasuredLeg is the measured leg with the widest worst gap — the one the sizing rule is applied against — and false when nothing has been measured at all.
func (*Entry) UnmeasuredLegs ¶
UnmeasuredLegs is every leg this entry has no evidence for, in the order Legs declares, so a message about them reads the same way twice.
type FixturePace ¶
type FixturePace struct {
// Interval is the pause the fixture leaves between two flushes.
//
// ZERO IS A STATEMENT AND NOT A BLANK. One of these fixtures writes
// its frames and then goes silent for the rest of the row, so there
// is no interval to state, and what its gap is made of is delivery
// plus the scheduler, from the response arriving. Which
// of the two a zero means is answered by the field below and by the
// entry's own Governs line; "nobody said" is a nil FixturePace, and
// the guard beside this package refuses that.
Interval time.Duration
// Flushes is how many times the fixture writes and flushes on the
// connection the gap is measured over.
//
// IT IS CHECKED AGAINST THE FIXTURE rather than transcribed beside
// it. The probe in internal/flow asserts that the script it is about
// to run has exactly this many frames at exactly the interval above,
// so a constant moved in one place and not the other reds at the
// measurement rather than sitting here describing a fixture that
// stopped existing. A record is pasted or it is retyped, and a
// retyped number is a number with a transcription error waiting in
// it.
Flushes int
}
FixturePace is the READ side's condition, and it is to a read-side number what a pinned pair of socket buffers is to a write-side one: the thing the gap was measured UNDER, stated where the gap is recorded so that neither can be read without the other.
WHY IT HAD TO BE WRITTEN DOWN, AND WHY IT HAD TO BE A CONSTANT ¶
Measured across twenty-one passes in one round: the worst gap a read-side probe reports IS the fixture's own widest pause between two flushes, to within a millisecond, every time. That is the honest answer to what a read-side window is a margin over — how long the machine can starve the server goroutine — and it has a consequence that took a round to see.
While anything about the fixture is DERIVED FROM THE WINDOW, a margin of five times a measured maximum cannot converge. The maximum of a heavy-tailed sample grows with how long you look; a wider window made the fixture deliver for longer; the longer delivery produced a larger maximum; five times that asked for a wider window. It went from 150 to 250 to 350 to 400 milliseconds inside a single round on exactly that treadmill, and every step of it was the rule being applied correctly.
AN INSTRUMENT THAT FOLLOWS ITS OWN READING CANNOT CONVERGE. So the fixture's pace and the length of what it delivers are STATED CONSTANTS in internal/flow, chosen once by a person, and this field is where the registry records which constants a leg's number was taken under. The window is then five times the measured maximum and stays there, because nothing downstream of it moves the fixture.
IT IS ON THE ENTRY AND NOT ON THE MEASUREMENT, which is the opposite of where the write side's condition lives, and the difference is real rather than tidy. A socket buffer is the KERNEL's answer to a request, so it differs per leg and is recorded per leg. A fixture's pace is this repository's own constant: it is the same number on all three legs by construction, and three copies of one constant would be three chances to disagree.
type Leg ¶
type Leg string
Leg is one of the three operating systems this project's gate runs. Socket buffer sizes, their autotuning and scheduling granularity all belong to the kernel and the runner, so a number measured on one leg says nothing about the other two.
type Measurement ¶
type Measurement struct {
// WorstGap is the longest interval observed between two consecutive
// progress events at the client, over every run.
WorstGap time.Duration
// Runs is how many runs stand behind WorstGap.
//
// TWENTY MEANS ONE PASS AND FORTY MEANS TWO, and which conditions
// those passes were is a live question rather than a convention.
// The gate runs these packages twice, plainly and under the race
// detector, and the rule is that a leg keeps the WORSE of the two —
// but for one round only the raced pass printed its figures, so the
// hosted legs here carry a single condition's number. Both passes
// publish now; the next retake of a hosted leg records the worse of
// two rather than the one that happened to be readable.
Runs int
// Date is when they were taken, as YYYY-MM-DD. A measurement with no
// date cannot be judged stale.
Date string
// Integrity is what the passes behind WorstGap say about
// THEMSELVES: whether the fixture held the pace this measurement
// assumes it held. A nil Integrity on a measured leg is not "the
// fixture was fine", it is nobody having looked, and the guard reds
// on it.
Integrity *PaceIntegrity
// FlushBudget is what a WRITE-THEN-SILENT fixture's own widest gap
// between flushes is allowed to be on this leg before the pass that
// produced it is called starved. It is the threshold the 3× rule is
// applied to for a fixture that states no interval, and it is what
// makes "no unpaced fixtures" true: every row now declares the
// quantity its starvation is measured against, and none is exempt.
//
// IT IS ON THE MEASUREMENT AND NOT ON THE FixturePace, which is the
// opposite of where the interval lives, and the reason is the reason
// given there in the other direction. An interval is this
// repository's own constant — the same number on all three legs by
// construction, so three copies would be three chances to disagree.
// A flush budget is not a constant anybody chose: it is how long
// THIS KIND OF MACHINE takes to get a goroutine back on a core, which
// differs per leg by an order of magnitude and is therefore measured
// per leg, dated, and retaken like any other reading here. It sits
// beside WorstGap because it comes off the same passes.
//
// BUT A BUDGET IS NOT RAISED BY ITS OWN OUTLIER. Defined as the widest
// gap on a valid pass, it can raise itself: a pause inside three times
// the budget is valid, becomes the widest, and moves the threshold out
// past the next pause, until nothing on the leg is ever starved.
// StreamGoesQuiet's darwin budget is held as a ruled ceiling for exactly
// that reason, and its entry shows the arithmetic.
//
// ZERO MEANS THIS FIXTURE STATES AN INTERVAL and the interval is the
// threshold. Zero on a fixture whose Pace.Interval is ALSO zero is
// nobody having looked, and the guard beside this package refuses it
// rather than letting it through as a threshold of nought — which
// would not be a lenient rule but the strictest possible one, marking
// every pass starved and stopping the leg at its cap.
FlushBudget time.Duration
// BlockPoint is the bytes the client handed over before it stopped
// making progress at all. WRITE SIDE ONLY: on the read side nothing
// is buffering on this client's behalf, so there is no such number
// and a value here would be an invention.
BlockPoint int64
// Pin is the socket-buffer pair WorstGap was measured under, and it
// says which MODE this leg is in. WRITE SIDE ONLY, for the same
// reason BlockPoint is: on the read side the gap is the far end's
// pacing plus the scheduler, and no buffer this client can set
// governs it.
//
// A nil Pin on a write-side measurement is not "unpinned", it is
// NOBODY SAID — and the guard reds on it, because what happens on
// that leg depends on the answer.
//
// # A LEG THAT CANNOT PIN IS A STOP, NOT A PAYER
//
// This paragraph used to promise the opposite, and the promise was
// arithmetically impossible. It said a leg that tried to pin and
// could not simply pays: a wider window, a margin over an autotuned
// buffer, and a fixture large enough to spend three of them. There
// is nothing to pay WITH. The upload row's fixture is derived from
// its window by pacingFor in internal/flow, and pacingFor REFUSES
// above a window of about 2.47 seconds, because past that the body
// it would have to pace exceeds this client's own 30 MB input limit
// — which corresponds to a worst gap over about 494 ms. Darwin's own
// autotuned gap was 434 ms. The leg the promise was written for was
// already inside a rounding error of the refusal, and the two legs
// nobody had measured were the ones the promise was about.
//
// THE LIMIT IS THE PRODUCT'S AND DOES NOT MOVE FOR A TEST. It is
// what this client tells a person their project may be, re-validated
// server-side; a suite that widened it to make one of its own rows
// affordable would be measuring a client nobody ships.
//
// So the behaviour is: a run whose pin does not hold REDS, at the
// row, naming the end that failed — "receive NOT PINNED" — and the
// entry for that leg records the failure in this field. Whether the
// leg is then written off as unpinnable, and what the row becomes
// there, is a ruling a person makes at a desk with the evidence in
// front of them. It is not a skip, and it is not a fixture that
// quietly grows until it trips a product limit somewhere else.
Pin *PinnedPair
}
Measurement is one leg's evidence for one window: the worst gap observed, over how many runs, on what date, and — on the write side — the socket buffers it was observed under.
A ZERO VALUE IS "NOT MEASURED", never "measured at zero". That distinction is the whole point of the type: an absent number and a number somebody chose look identical once they are both durations, and the guard beside this package can only refuse the first if the two are distinguishable.
func (Measurement) Measured ¶
func (m Measurement) Measured() bool
Measured reports whether this leg has evidence behind it.
All three fields are required and each is checked for what it is rather than for being non-zero: a duration with no run count is one sample; a run count under the floor is not a distribution; and a date that does not PARSE cannot be compared with anything, which is the only thing a date is for here. A string that merely is not empty passes an emptiness test and tells a reader nothing — "soon", "last week" and "2026-13-45" are all non-empty.
func (Measurement) Pinned ¶
func (m Measurement) Pinned() bool
Pinned reports whether this leg's gap was measured over a connection whose buffers were pinned at BOTH ends and confirmed by reading them back. It is the question "which mode is this leg in", and everything about the cost of the row it stands behind follows from the answer.
type PaceIntegrity ¶
type PaceIntegrity struct {
// Attempts is every pass this leg ran, the thrown-away ones
// included. Valid and Starved divide it in two: the passes whose
// fixture held its stated pace within the threshold, and the passes
// whose did not and were retaken. WorstGap is a maximum over the
// Valid ones only, and on a leg that finished, Valid is the count
// the probe asked for rather than whatever survived.
//
// # STARVED OVER ATTEMPTS IS A RATE, AND THE RATE IS THE POINT
//
// A runner's noise is now MEASURED rather than reddened. The rule
// that preceded this one produced, on a noisy leg, a red and no
// number — so the quantity everybody was arguing about existed
// nowhere except in the memory of whoever was interrupted. Recorded
// per leg and per retake, it is something a later reader can plot:
// how often this machine, on this leg, under this condition, was not
// an instrument.
//
// The three numbers are ONE ARITHMETIC FACT and the guard beside
// this package says so — an attempt either measured the client or
// was discarded and retaken, so Valid plus Starved is Attempts.
// Recording Valid and Starved alone would leave the rate's
// denominator to be inferred, and the inference is only right while
// nothing retakes.
Attempts int
Valid int
Starved int
// ThresholdNum over ThresholdDen is the multiple of the stated pace
// a fixture may miss by and still be counted. It is recorded here
// rather than only in the probe because a number and the rule that
// admitted it are one fact, and the probe checks this field against
// the rule it is about to apply.
ThresholdNum int
ThresholdDen int
// StatedPace and Flushes are the FIXTURE THIS LEG'S NUMBER WAS TAKEN
// THROUGH, recorded per leg rather than only per entry.
//
// # AN ENTRY-LEVEL PACE CANNOT SAY WHICH LEGS PREDATE IT
//
// The entry carries one Pace and the probe checks it against the
// fixture it is about to run, so a constant moved in one place and
// not the other reds at the measurement. What that cannot see is a
// fixture change made on ONE machine: the leg being remeasured
// agrees with the new constant, the other two legs' numbers were
// taken through the old one, and nothing anywhere says so. It
// happened on 2026-09-11 — the keep-alive fixture went 76 flushes to
// 36 and the partial line's 116 to 61 while linux and windows still
// carried figures from the longer ones, all of it green.
//
// So each leg's record says what it ran through, and the guard reds
// when that has drifted from the entry's own. A number and the
// fixture it was measured through are one fact, and the fact is per
// leg because the measurement is.
//
// Zero pace means the fixture STATES no interval — it writes and goes
// silent — and the threshold its passes were judged against is the
// FlushBudget below rather than this field. It no longer means
// "there is no integrity test to apply": that exemption was the hole
// this pairing closed.
StatedPace time.Duration
// FlushBudget is the threshold a write-then-silent fixture's passes
// were judged against, recorded beside the pace so a reader of this
// record can tell WHICH of the two the 3× was applied to without
// going back to the entry. Exactly one of StatedPace and FlushBudget
// is non-zero on a well-formed record, and the guard says so.
FlushBudget time.Duration
Flushes int
// WorstFixtureGap is the widest gap the fixture left, across ALL
// ATTEMPTS including the ones that were thrown away. It is the
// number that says how far from a measuring instrument this leg's
// runner was, and retaking the starved attempts without recording it
// would hide exactly that — a probe that quietly retook six passes
// and reported a clean twenty would be describing a machine nobody
// ran on.
WorstFixtureGap time.Duration
// ValidGapMin, ValidGapMedian and ValidGapMax are the fixture's own
// gap across the passes that were ADMITTED — the shape of the
// population the threshold let in, rather than the one number at the
// top of it.
//
// # A THRESHOLD IS A LINE THROUGH A DISTRIBUTION NOBODY HAD LOOKED AT
//
// Three times the stated pace was chosen between two readings: the
// ordinary passes near 1.25× and the starved one at 15.8×. That is a
// defensible line and it says nothing about what lies between. The
// first retake under the rule produced a darwin partial-line maximum
// of 47.297583 ms whose own fixture gap was 47.14675 ms — 2.36× the
// stated pace, admitted, and the reading that set that window.
//
// So the record now carries the distribution rather than its
// endpoint. Divided by StatedPace these three are the ratio spread,
// per leg, per retake: if the admitted passes cluster near 1.2× with
// one at 2.4×, the line is in open space; if they run continuously
// from 1× to 3×, there is no gap for a line to sit in and the
// threshold is dividing one population rather than separating two.
// That is the evidence the threshold moves on — not one entry's
// unlucky pass.
// A RECORD IS ONE PASS'S, not an aggregate of several. A leg is
// measured over a series and keeps the pass whose CLIENT gap was
// worst, so every field here came from one run of the probe and the
// attempts that run happened to spend. The alternative — a min over
// one pass, a median over another, a maximum over a third — puts a
// median in the record that no sample produced.
ValidGapMin time.Duration
ValidGapMedian time.Duration
ValidGapMax time.Duration
}
PaceIntegrity is a measurement's report on its own instrument.
AN INSTRUMENT THAT RECORDS ITS OWN STARVATION AS THE SUBJECT'S MARGIN ¶
Both timing ROWS already tell these apart. Each one reads the fixture's widest gap between its own flushes and refuses when the fixture itself paused past the window, saying in terms that the row "measured the machine rather than the client". The PROBE beside them did not. It recorded the starved gap as the leg's worst, the registry sized a window at five times it, and the row's fixture then grew to span three and a half of that — which is raising the number until the failures stop, performed by the instrument instead of by a person.
The instance, on the gate's own macOS runner, 2026-09-10: the client's worst gap was 315.903625 ms and the fixture's own widest gap between two flushes was 315.881875 ms, twenty-two MICROSECONDS apart, at a stated 20 ms pace. The client did not wait. The runner stopped the server goroutine for a third of a second and the client reported it faithfully.
So a pass now declares whether it measured anything. A fixture that missed its own stated pace by more than the threshold below did not, and its number is excluded from the maximum rather than becoming it.
A READING DISCARDED FOR CARRYING NO INFORMATION CANNOT ALSO BE INFORMATION ¶
That rule used to have a second half, and the second half was calibrated wrong. A leg in which more than one pass in five starved was a STOP — "this runner cannot hold the fixture's pace" — and it fired three times in one working day with no client-margin breach underneath any of them. Every window held with room: 32 ms against 255 ms, 1.2 ms against 55 ms. Five of twenty starved on one branch and six of twenty on another probe in the same command; one of twenty in the same command on the main line; and the branch that produced the worst readings produced zero of twenty on all six probes when the identical command was run again. That is a distribution, and the old rule drew a line across the middle of it and called everything past the line a broken runner.
It was also not measuring what its name said. "One pass in five starved" is a statement about a sample the probe CHOSE TO KEEP, and it had no reason to keep one: a starved pass is excluded from the maximum precisely because it measured nothing. Having discarded a reading as uninformative, the same rule then counted it as evidence against the runner — and the cost was paid in the wrong direction, since a starved pass makes the sample SMALLER and the answer to a short sample is another reading.
So a starved pass is DISCARDED AND RETAKEN. It does not count toward the passes a leg asked for; the probe takes another one, the way every other instrument does when a reading is spoiled, and it stops only after spending a bounded number of attempts without reaching the count. Nothing about WHAT COUNTS as starved moved with this: the threshold below is the same three, and the window is the same five times the valid maximum. What changed is only what the probe does with a pass that starved.
func (*PaceIntegrity) Ratios ¶
func (p *PaceIntegrity) Ratios() (min, median, max float64)
Ratios renders the admitted passes' fixture gaps as multiples of the stated pace, which is the form the threshold is written in.
IT RETURNS ZEROS FOR AN UNPACED FIXTURE rather than dividing by one. A fixture with no pace has no ratio to a pace, and a 1.0 there would read as "held it exactly" — a claim about a test that was never run.
func (*PaceIntegrity) StarvationRate ¶
func (p *PaceIntegrity) StarvationRate() float64
StarvationRate is the share of this leg's attempts that measured the machine rather than the client and were thrown away: Starved over Attempts.
IT IS A COLUMN AND NOT A GATE, which is the whole of the change it arrived with. Nothing refuses on this number. What refuses is a probe that spent its attempts without reaching the passes it asked for — which is a statement about whether there is a measurement here at all, rather than about how much work it took to get one.
THE DENOMINATOR IS ATTEMPTS, and that is the field this method exists to pin down. Under a probe that never retook a pass, attempts and passes were the same twenty and either would have read correctly; the two only separate once a spoiled reading is replaced, and a rate whose denominator was a fixed twenty would then quietly report a fraction of the wrong thing. The record carries the number rather than leaving it to be derived.
IT RETURNS ZERO FOR A LEG THAT ATTEMPTED NOTHING rather than dividing by one. No attempts is nobody having run the probe, and a clean 0.0 there would read as a runner that never starved — a claim about a measurement that does not exist.
type Pin ¶
type Pin struct {
// Requested is the buffer size handed to setsockopt, in bytes.
Requested int
// ReadBack is what getsockopt reported afterwards, in bytes. Zero
// means nothing was read back, which is the same as no pin at all —
// see Held.
//
// IT IS AN INSTANT AND NOT A DURATION, which is the whole reason the
// field below exists. Read one syscall after the request, it says
// the kernel agreed at that moment; it says nothing whatever about
// the seconds afterwards during which the body actually moves.
ReadBack int
// Sustained is what the kernel held this buffer at WHILE a body was
// moving over the connection, sampled repeatedly rather than once.
// Nil means nobody sampled it.
//
// # A READ-BACK PROVES THE REQUEST WAS HONOURED, NOT THAT IT STUCK
//
// This field was added in round 3 because the difference turned out
// to be the whole measurement on one of the three legs. Measured on
// darwin, 2026-09-10: the client's SO_SNDBUF read back what it asked
// for and was still that when the last byte went out, and the
// accepting end's SO_RCVBUF read back the same figure and was
// several times it for every sample taken after the first two
// hundred milliseconds — up to 646,336 against a 131,072 request,
// and up to 539,008 against a 16,384 one. macOS ships
// net.inet.tcp.doautorcvbuf=1 and setting SO_RCVBUF does not turn it
// off: re-setting the option on every drain step held the FLOOR at
// the requested size and moved the ceiling not at all.
//
// So a record carrying only ReadBack can say "measured under a
// 16 KiB receive buffer" about a connection that spent its whole
// life at four hundred kilobytes, and nothing in the record would
// disagree. Sampling is what turns that from a claim into a number,
// and the number is per leg because it is the kernel's behaviour and
// not this repository's.
Sustained *Sustained
// Err is the failure, rendered, or "" when there was none. It is a
// STRING rather than an error because this is a transcription of
// what a run observed, written out by hand into a record — an error
// value in a package-level literal would be a live object standing
// in for a thing that happened once, on a machine, in the past.
Err string
}
Pin is ONE END's claim about a socket buffer: the size that was asked for, the size the kernel reported back when asked, and what went wrong if anything did.
A PIN IS A CLAIM, SO IT IS READ BACK ¶
setsockopt is free to clamp a request, to round it, to double it, or — under a sandbox or a hardened kernel — to accept it and do nothing. It reports none of that: the call returns success and the socket keeps whatever buffer the kernel decided it should have. So a window sized from a gap "measured under a 128 KiB buffer" can perfectly well have been measured under a buffer nobody chose, and nothing anywhere would say so. Setting the option proves only that the request was made; getsockopt afterwards is what proves the kernel agreed.
LINUX REPORTS THE DOUBLED VALUE, AND THAT IS NOT DISAGREEMENT ¶
A Linux kernel stores twice what SO_SNDBUF/SO_RCVBUF asked for — the second half is its own bookkeeping overhead — and getsockopt hands that doubled number straight back. So on Linux ReadBack == 2*Requested is the kernel HONOURING the request, and treating it as a refusal would throw away the only leg where the pin is most certainly applied. Darwin and Windows report back what was asked for, give or take their own clamping. That is why ReadBack is RECORDED PER LEG rather than compared against Requested: the relation between the two is the kernel's business, and the only thing that has to hold is that the run which took the gap and the run reading this record saw the SAME ReadBack.
AND THE WINDOW IS COMPUTED FROM THE GAP UNDER ReadBack ¶
Never from Requested. Requested is what was typed; ReadBack is the condition the number was measured in, and a measurement's condition is part of the number.
func (Pin) Held ¶
Held reports whether this end really was pinned: the kernel answered, and it answered with a size that is an ANSWER TO THE REQUEST. A Pin carrying an Err is not a weaker pin, it is the record of a leg that could not pin — which is a legitimate thing to write down and a different mode to run in.
THE COHERENCE BAND, AND WHY A BARE "NOT ZERO" WAS NOT ENOUGH ¶
A read-back is only evidence if it stands in a known relation to what was asked for. Linux stores twice the request and hands the doubled number straight back, so the honest band is [Requested, 2*Requested] and nothing else in it is honest: a kernel that reported half the request clamped it, and one that reported thirty times it was answering about a buffer nobody chose. Outside the band the pin is not CLAIMED — the record still says what happened, and nothing reads it as a condition.
This was measured rather than reasoned about: before the band existed, a Pin of {Requested: 131072, ReadBack: 1} passed every guard in this package. One byte is not a socket buffer on any operating system, and the check that let it through was asking whether a number was positive.
type PinnedPair ¶
type PinnedPair struct {
// Send is the CLIENT's SO_SNDBUF — the end this repository ships.
Send Pin
// Receive is the FIXTURE's SO_RCVBUF, set on every connection the
// object-store double accepts.
Receive Pin
}
PinnedPair is BOTH ENDS of the connection a write-side gap was measured over, and the pair is the unit because a socket option has an END and "the test connection" names two sockets.
An upload has the client SENDING and the fixture RECEIVING. The gap being bounded is the time for the client's send buffer to free space, and that is governed by how fast the far end drains — which is set by the RECEIVE buffer at the other end and by how often that end can advertise a larger window. Pin only the sender and the number measured is the receiver's autotuning; pin only the receiver and it is the sender's. Neither half is the measurement.
The two Pins carry the same Requested by construction here, and are still recorded separately, because each end's kernel answers for itself.
func (*PinnedPair) Held ¶
func (p *PinnedPair) Held() bool
Held reports whether both ends were really pinned. A pair with one end held is not half a pin; it is a gap measured against the other end's autotuning, which is the thing the pair exists to remove.
type Side ¶
type Side string
Side is which end of the connection the client is on, and it decides what the gap between two progress events is made of. The two are separate quantities measured by separate methods, and one measurement can never describe both.
const ( // Write: the client is pushing a body. The gap between two progress // events is the time for the kernel's send buffer to free space, // which is governed by how fast the far end reads. A write side has // a BLOCK POINT — the bytes handed over before the client stops // making progress at all. Write Side = "write" // Read: the client is consuming a stream. The gap between two // progress events is how long the far end waits before writing more, // plus whatever the scheduler adds. Nothing is buffering on this // client's behalf, so a read side has NO block point and asking for // one would be meaningless. Read Side = "read" )
type Sustained ¶
type Sustained struct {
// Samples is how many times the buffer was read while a body was
// moving. Zero is "nobody looked", which the rows keep separate from
// "it did not move".
Samples int
// Low and High are the smallest and largest sizes seen across those
// samples, in bytes.
Low, High int
}
Sustained is a buffer's range over a body, rather than its value at an instant.
LOW AND HIGH RATHER THAN A MEAN, because the question is not "what was it usually" but "was it ONE size". A mean of a buffer that doubled halfway through is a number that describes no moment of the transfer, and a condition is either held or it is not.
Source Files