NAME
Net::QUIC::Stream - one QUIC byte stream
SYNOPSIS
Send bytes:
$stream->send("hello");
$stream->finish;Read bytes:
while (defined(my $bytes = $stream->next_data)) {
handle_bytes($bytes);
}Check for a clean peer FIN:
if ($stream->remote_finished) {
...
}Abort the stream:
$stream->reset($application_error_code);DESCRIPTION
Net::QUIC::Stream represents one QUIC byte stream.
A QUIC stream is an ordered sequence of bytes.
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.
Applications that need message boundaries should add their own framing above the QUIC stream.
A Stream does not own a socket. UDP and timer integration normally stays in Net::QUIC::Driver.
STREAM DIRECTION
A bidirectional stream allows both endpoints to send.
A unidirectional stream allows only its creator to send application bytes.
Use:
$stream->can_sendand:
$stream->can_receivewhen code needs to handle either kind.
METHODS
id
my $id = $stream->id;Returns the QUIC stream ID.
local_initiated
if ($stream->local_initiated) {
...
}Returns true when this endpoint opened the stream.
bidirectional
if ($stream->bidirectional) {
...
}Returns true for a bidirectional stream and false for a unidirectional stream.
can_send
Returns true when this endpoint is allowed to send application bytes on the stream.
can_receive
Returns true when this endpoint is allowed to 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.
Large sends are stored internally in fixed-size pieces so fully acknowledged earlier bytes can be released without keeping the entire original send allocation alive.
When this Stream belongs to a Connection obtained through Driver, send automatically notifies Driver that QUIC may have new output.
No extra integration call is required.
finish
$stream->finish;Closes the local send side cleanly after all bytes already queued with send.
This sends QUIC FIN.
It does not discard queued data.
On a bidirectional stream, the peer may continue sending bytes back after this endpoint calls finish.
next_data
while (defined(my $bytes = $stream->next_data)) {
...
}Returns the next received chunk, or undef when no received data is currently waiting.
Always test with defined.
Reading data returns its receive flow-control credit to QUIC. With a Driver integration, any protocol output made possible by that credit is serviced automatically.
remote_finished
Returns true after a clean FIN has been received from the peer.
This means the peer has finished its send side.
reset
$stream->reset;or:
$stream->reset($application_error_code);Aborts the local stream send side with a QUIC application error code.
The code defaults to zero.
remote_reset_code
my $code = $stream->remote_reset_code;Returns the application error code when the peer reset the stream, or undef if no peer reset has been received.
local_reset_code
my $code = $stream->local_reset_code;Returns the application error code passed to reset on this endpoint, or undef if this endpoint has not reset the stream.
Keeping local and remote reset codes separate makes the reset direction unambiguous.
closed
Returns true after ngtcp2 reports that the stream is fully closed.
OBJECT LIFETIME
A Stream object keeps its Net::QUIC::Connection alive.
Closed native stream state remains available while a Stream object still needs it. This keeps final status and unread buffered receive data usable after QUIC closes the stream.
Once the native stream is closed and no public Stream object or pending incoming-stream queue entry needs it, Net::QUIC reclaims that state.
Dropping a Stream object before native close does not discard already queued transmit data. Net::QUIC keeps the native stream state until QUIC can finish or close it.