pub struct Work {
pub busy_nanos: u64,
pub items: u64,
}Expand description
Cumulative work done by one stage.
§Busy time, never wall time
busy_nanos must be time a worker spent doing the work, with blocking
excluded — a consumer must not count time waiting for input, a producer must
not count time blocked on a full output queue or on the source.
This is the single most important contract in the crate, and the whole
control law rests on it. Wall time contains blocking, and blocking is a
function of the split being controlled, so a controller built on wall time
feeds its own actuation back into its measurement. That endogeneity is what
makes utilisation-style signals degenerate — see ProducerPressure.
Busy time has the opposite property: over a window in which the pipeline
moved X items, the two stages spent X * s_producer and X * s_consumer
thread-nanoseconds respectively, so their ratio is the ratio of per-item
costs regardless of how many threads either side had. That is the quantity
the split is solved from, and it is why no shared unit of work is needed:
the X cancels.
§Items are a progress measure, not a shared currency
items is used only to compare throughput at one split against throughput at
another — for ratifying a move and for noticing a regime change. It need only
be consistent over time within a stage. The two stages may count entirely
different things (records here, decompressed bytes there) without affecting
the split, because the split never divides one by the other.
Fields§
§busy_nanos: u64Nanoseconds of real work, summed over this stage’s workers.
items: u64Progress in whatever unit is natural for this stage.