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.
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.
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.