Documentation
¶
Overview ¶
Package benchrun measures what running a command costs: wall time and peak resident set size. It is the shared measurement core under `task bench:cold` (mache-2de6c0) and the scale gate that will follow (mache-543943).
Peak RSS is the point. The cold-path budget is "does a first `mache build` fit a 4-core/16 GB laptop with an IDE already open", and wall time cannot answer that: a run that pages is slow for a reason no timing number attributes. Bytes are also machine-independent in a way milliseconds are not, which is why the hard gate is on memory and artifact size while wall time stays advisory.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FileBytes ¶
FileBytes is the on-disk size of path plus its SQLite sidecars. A .db whose pages are still in a 300 MB write-ahead log has not stopped costing the disk 300 MB, so the sidecars count toward the artifact budget.
func HumanBytes ¶
HumanBytes renders a byte count the way the budget is written and argued about — decimal GB, two decimals — so a reported number and a budget number can be compared by eye without a unit conversion in the reader's head.
Types ¶
type Budget ¶
type Budget struct {
// PeakRSSBytes is the memory ceiling. Above it a 16 GB laptop with an
// IDE open starts paging, and the wall time stops meaning anything.
PeakRSSBytes int64 `toml:"peak_rss_bytes"`
// LeylineDBBytes caps the intermediate parse artifact.
LeylineDBBytes int64 `toml:"leyline_db_bytes"`
// ProjectionDBBytes caps the artifact the user keeps.
ProjectionDBBytes int64 `toml:"projection_db_bytes"`
// WallMsAdvisory is reported against, never enforced.
WallMsAdvisory int `toml:"wall_ms_advisory"`
}
Budget is the cold-path envelope: what a first `mache build` is allowed to cost on the machine most people actually have (mache-2de6c0). The three byte limits are HARD — a run that exceeds any of them fails. Wall time is advisory and can never fail a run: timing gates flake on shared CI runners, and a gate that flakes gets disabled, which is worse than no gate.
func LoadBudget ¶
LoadBudget reads the committed budget. A limit that is missing or non-positive is an ERROR, not a pass: a zero ceiling read as "no limit" would turn a typo into a permanently green gate, which is the one failure mode a budget file must not have.
type Measurement ¶
type Measurement struct {
// Command is the command line, for reporting.
Command string
// Wall is elapsed real time — what the user waits.
Wall time.Duration
// PeakRSS is the high-water resident set size in bytes.
//
// It comes from the rusage wait4 returns for the child, which folds in
// any descendant the child itself waited for — so `mache build`'s number
// covers the `leyline parse` it spawns. That fold is a MAX, not a sum:
// it answers "was any single process ever this big", not "how much was
// resident at once". For this harness the two coincide, because mache
// runs the parse to completion before it projects. A phase that ran them
// concurrently would need a sampler instead.
PeakRSS int64
}
Measurement is one command's cost.
func Run ¶
Run executes name with args, writing the command's own output to out, and reports what it cost. env entries are appended to the current environment (later entries win, which is how exec applies them).
A non-zero exit is returned as an error AND measured: a run that died after allocating 4 GB is exactly the data point the budget exists to catch, so the Measurement is always usable.
Source Files