pub async fn stream<W: Write>(
conn: &mut Conn,
gated: &Gated,
sink: Sink<'_, W>,
pipeline: &Pipeline,
conversion: &Conversion,
ceiling: usize,
token: &CancellationToken,
) -> Result<u64>Expand description
Runs a read and writes each row straight onto the flow.
Nothing here holds a collection of rows: a row is shaped, written and forgotten, so the memory cost does not grow with the size of the result set. The output operations run as stages of that flow rather than over a gathered payload, so asking for a ceiling, a filter or a projection costs no memory either.
sink carries the channel, the shape and the tail the closing record
declares besides the count: the command that produced the set and the
destination it came from, which a flow has no envelope of its own to carry
(FR-143).
The closing record is written only when the flow reached its end with everything it promised. A failure mid-way returns without it, and so does a flow the volume ceiling cut short, which is how the caller tells a cut set from a whole one.
§The row ceiling ends a flow without breaking it
ceiling is this tool’s own ceiling on returned rows, and it is counted
over the rows ARRIVING from the server rather than over the rows leaving,
which is where the gathered path counts it too. Counting the ones leaving
would answer one request two different ways the moment a filter dropped
anything, because the gathered path cuts at the read and filters afterwards.
A flow the ceiling ended still closes with the record that declares it, carrying the gap the ceiling left. The set ended because this tool decided to end it, and a decision is not a loss: a flow cut by a dropped channel still leaves the output with no closing record at all, and that difference is the only thing a reader of the primary channel has to tell an interrupted set from a complete one.
§Errors
Returns the mapped driver failure when the channel is lost, and a limit failure when the reader closed the output channel.