NAME
Net::QUIC::Stream - one reliable QUIC byte stream
DESCRIPTION
A Stream is one ordered sequence of bytes inside a Net::QUIC::Connection.
It is not a sequence of application messages.
One call to:
$stream->send($message);does not guarantee one matching next_data result on the peer.
If the application needs message boundaries, add framing above the Stream.
BASIC USE
Send bytes:
$stream->send("hello");
$stream->finish;Read available bytes:
while (defined(my $bytes = $stream->next_data)) {
handle_bytes($bytes);
}Check whether the peer finished cleanly:
if ($stream->remote_finished) {
...
}STREAM DIRECTION
A bidirectional Stream allows both endpoints to send.
A unidirectional Stream allows only the endpoint that created it to send application bytes.
Use:
$stream->can_send
$stream->can_receivewhen code needs to handle either kind.
METHODS
id
my $id = $stream->id;Returns the QUIC stream ID.
Most applications do not need to interpret the numeric value.
local_initiated
if ($stream->local_initiated) {
...
}Returns true when this endpoint opened the Stream.
bidirectional
Returns true for a bidirectional Stream.
Returns false for a unidirectional Stream.
can_send
Returns true when this endpoint can send application bytes on the Stream.
can_receive
Returns true when this endpoint can receive application bytes on the Stream.
send
$stream->send($bytes);Queues bytes for reliable ordered delivery.
The bytes are copied into Net::QUIC-owned memory.
When the Stream belongs to a Connection obtained through Net::QUIC::Driver, Driver is notified automatically when new transport work is needed.
If the Connection has an explicit "send_buffer_limit" in Net::QUIC::Connection, send stays all-or-nothing and throws rather than exceeding that limit. Use "send_some" when partial acceptance is wanted.
send_some
my $accepted = $stream->send_some($bytes);Advanced bounded transmit interface.
The Connection must first have a "send_buffer_limit" in Net::QUIC::Connection configured.
Returns the number of prefix bytes copied into Net::QUIC-owned transmit memory. This can be zero or less than length($bytes) when the configured connection-wide buffer is full.
The caller retains ownership only of bytes that were not accepted and may release or reuse the accepted input after this method returns.
When send_some accepts fewer bytes than requested, pause the producer. "on_stream_activity" in Net::QUIC::Connection wakes protocol engines when ACK or other Stream progress can make more buffer space available.
send_buffered_bytes
my $bytes = $stream->send_buffered_bytes;Returns the number of this Stream's transmit data bytes currently retained by Net::QUIC.
It includes data that has been sent but is still retained until peer acknowledgement.
finish
$stream->finish;Finishes this endpoint's send side cleanly after all already queued bytes.
This is the normal way to say:
I am done sending.It does not discard queued data.
On a bidirectional Stream, the peer can continue sending data back.
next_data
while (defined(my $bytes = $stream->next_data)) {
...
}Returns the next received byte chunk.
Returns undef when no received data is currently waiting.
Always test with defined.
Reading data also returns receive flow-control credit to QUIC automatically.
Do not mix next_data with "next_data_chunk" or "consume" on the same Stream.
next_data_chunk
my ($bytes, $fin) = $stream->next_data_chunk;This is an advanced receive interface for protocol engines.
It returns the next received byte chunk without returning receive flow-control credit to QUIC.
In list context it returns:
($bytes, $fin)$fin is true when this chunk carries the peer's clean end-of-stream marker.
In scalar context it returns an array reference containing those same two values.
Returns undef, or an empty list in list context, when no received data is currently waiting.
Each chunk is delivered only once. After processing the bytes, report the number actually consumed with "consume".
Do not mix next_data_chunk with "next_data" on the same Stream.
consume
$stream->consume($byte_count);Returns receive flow-control credit for bytes previously delivered by "next_data_chunk".
The byte count may be smaller than the amount delivered. Additional bytes may be consumed later.
A count of zero is valid.
It is an error to consume more bytes than have been delivered and not already consumed.
Calling consume selects the explicit receive mode for the Stream, even when the byte count is zero. Do not use "next_data" after selecting explicit receive mode.
acked_offset
my $offset = $stream->acked_offset;Returns the number of bytes from the start of this Stream that the peer has acknowledged contiguously.
The value starts at zero and never moves backward.
This is an advanced protocol-engine interface. Ordinary applications normally do not need acknowledgement offsets.
remote_finished
Returns true after the peer cleanly finished its send side.
reset
$stream->reset;or:
$stream->reset($application_error_code);Abruptly aborts this endpoint's send side.
Queued transmit data that has not completed can be discarded.
On a bidirectional Stream, the receive side remains independent and can still receive data from the peer.
The application error code defaults to zero.
For an ordinary clean finish, use "finish" instead.
stop_sending
$stream->stop_sending;or:
$stream->stop_sending($application_error_code);Abruptly stops this endpoint's receive side and asks the peer to stop sending.
Unread buffered receive data is discarded.
On a bidirectional Stream, this endpoint's send side remains independent.
The application error code defaults to zero.
remote_reset_code
my $code = $stream->remote_reset_code;Returns the application error code received when the peer reset its send side.
Returns undef when no peer reset has been received.
local_reset_code
my $code = $stream->local_reset_code;Returns the application error code this endpoint passed to "reset".
Returns undef when this endpoint has not reset its send side.
remote_stop_sending_code
my $code = $stream->remote_stop_sending_code;Returns the application error code received when the peer asked this endpoint to stop sending.
Returns undef when no such request has been received.
local_stop_sending_code
my $code = $stream->local_stop_sending_code;Returns the application error code this endpoint passed to "stop_sending".
Returns undef when this endpoint has not stopped its receive side.
early_data
if ($stream->early_data) {
...
}Returns true when this Stream carried 0-RTT early data.
This matters because 0-RTT data can be replayed.
A server can use this flag even after the handshake finishes to keep replay-sensitive application handling separate.
closed
Returns true when QUIC has completely closed the Stream.
OBJECT LIFETIME
A Stream object keeps its Connection alive.
Dropping the Perl Stream object does not discard transmit data that QUIC still needs to send or finish.
Final status and unread buffered receive data remain available while the public Stream object still needs them.