Standard Library

class ChunkedSink

The writer for a streaming HTTP response body.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A handler returns HttpResponse::ofStream(...) with a function that receives a ChunkedSink. Each write sends its text as one chunk, so you write plain text and never chunk sizes, and end finishes the response. Writes wait until the data has been handed to the network, so a slow client slows the writer down instead of filling memory. Several callbacks may write at the same time; their chunks are sent whole and in the order the calls were made.

After the response has ended or the connection has failed, write and end do nothing. onClose reports a connection that was lost before the response was finished. The server creates the sink; you only use the one you are given.

Examples

A sink on a connection that is already closed

ChunkedSink sink = ChunkedSink(TcpStream(-1));
sink.onClose(() => console.writeln("connection lost"));
console.writeln(sink.isClosed());
sink.write("hello");
console.writeln(sink.isClosed());

false
connection lost
true

Constructors

new

new(TcpStream c)

Creates a sink that writes chunks to a connection.

The server does this for you when it starts a streaming response; you rarely need to call it yourself.

Parameters

c

The connection to write to.

Examples

ChunkedSink sink = ChunkedSink(TcpStream(-1));
console.writeln(sink.isClosed());

false

Methods

end

end() -> void

Finishes the response by sending the final zero-size chunk.

The call waits until the chunk has been handed to the network. The connection may then be reused for the next request. It does nothing if the sink is already closed. If the final chunk cannot be sent, the sink is closed as lost and the function given to onClose runs.

Examples

ChunkedSink sink = ChunkedSink(TcpStream(-1));
sink.end();
console.writeln(sink.isClosed());

true

See also: write

isClosed

isClosed() -> bool

Tells whether the response has finished or failed.

It is true after end has completed and after the connection was lost. Writing to a closed sink has no effect.

Returns

true when no more data can be written.

Examples

ChunkedSink sink = ChunkedSink(TcpStream(-1));
console.writeln(sink.isClosed());
sink.end();
console.writeln(sink.isClosed());

false
true

onClose

onClose(() => void cb) -> void

Sets the function that runs when the connection is lost before the response is finished.

It runs at most once, and only for a premature loss: it does not run after a normal end. If the connection was already lost when you call onClose, the function runs immediately.

Parameters

cb

The function to run when the connection is lost.

Examples

ChunkedSink sink = ChunkedSink(TcpStream(-1));
sink.onClose(() => console.writeln("connection lost"));
sink.write("hello");
sink.write("more");

connection lost

write

write(string data) -> ChunkedSink

Sends text to the client as one chunk.

The call waits until the chunk has been handed to the network. Writing an empty string does nothing, because an empty chunk would end the body. After end, or after the connection was lost, it does nothing at all. If the chunk cannot be sent, the sink is closed and the function given to onClose runs.

Parameters

data

The text to send.

Returns

This sink, so calls can be chained.

Examples

Writing to a connection that is gone closes the sink

ChunkedSink sink = ChunkedSink(TcpStream(-1));
sink.write("");
console.writeln(sink.isClosed());
sink.write("data");
console.writeln(sink.isClosed());

false
true

See also: end

Operators

<<

<<(string data) -> ChunkedSink

Sends text to the client as one chunk; the same as write.

Parameters

data

The text to send.

Returns

This sink, so writes can be chained: sink << "a" << "b".

Examples

ChunkedSink sink = ChunkedSink(TcpStream(-1));
sink << "a" << "b";
console.writeln(sink.isClosed());

true

See also: write

See also

• ofStream — Creates a streaming response whose body is written over time.