Struct Connection

pub struct Connection<C, B>
where
    C: Connection<B>,
    B: Buf,
{
    pub inner: ConnectionInner<C, B>,
    /* private fields */
}

Available on crate feature h3 only.

Client connection driver

Maintains the internal state of an HTTP/3 connection, including control and QPACK. It needs to be polled continuously via poll_close(). On connection closure, this will resolve to Ok(()) if the peer sent HTTP_NO_ERROR, or Err() if a connection-level error occurred.

shutdown() initiates a graceful shutdown of this connection. After calling it, no request initiation will be further allowed. Then poll_close() will resolve when all ongoing requests and push streams complete. Finally, a connection closure with HTTP_NO_ERROR code will be sent to the server.

Examples

Drive a connection concurrently

// Run the driver on a different task
tokio::spawn(async move {
    future::poll_fn(|cx| connection.poll_close(cx)).await;
    Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
})

Shutdown a connection gracefully

// Prepare a channel to stop the driver thread
let (shutdown_tx, shutdown_rx) = oneshot::channel();

// Run the driver on a different task
let driver = tokio::spawn(async move {
    tokio::select! {
        // Drive the connection
        closed = future::poll_fn(|cx| connection.poll_close(cx)) => closed,
        // Listen for shutdown condition
        max_streams = shutdown_rx => {
            // Initiate shutdown
            connection.shutdown(max_streams?);
            // Wait for ongoing work to complete
            future::poll_fn(|cx| connection.poll_close(cx)).await
        }
    };

    Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
});

// Do client things, wait for close condition...

// Initiate shutdown
shutdown_tx.send(2);
// Wait for the connection to be closed
driver.await?

Fields

inner: ConnectionInner<C, B>

TODO: breaking encapsulation for RFC9298.

Implementations

impl<C, B> Connection<C, B>

where C: Connection<B>, B: Buf,

pub async fn shutdown( &mut self, _max_push: usize, ) -> Result<(), ConnectionError>

Initiate a graceful shutdown, accepting max_push potentially in-flight server pushes

pub async fn wait_idle(&mut self) -> ConnectionError

Wait until the connection is closed

pub fn poll_close(&mut self, cx: &mut Context<'_>) -> Poll<ConnectionError>

Maintain the connection state until it is closed

Trait Implementations

impl<C, B> ConnectionState for Connection<C, B>

where C: Connection<B>, B: Buf,

fn shared_state(&self) -> &SharedState

Get the shared state

fn get_conn_error(&self) -> Option<ErrorOrigin>

Get the connection error if the connection is in error state because of another task

fn set_conn_error(&self, error: ErrorOrigin) -> ErrorOrigin

tries to set the connection error

fn set_conn_error_and_wake<T>(&self, error: T) -> ErrorOrigin

where T: Into<ErrorOrigin>,

set the connection error and wake the connection

fn settings(&self) -> Cow<'_, Settings>

Get the settings

fn set_closing(&self)

Set the connection to closing

fn is_closing(&self) -> bool

Check if the connection is closing

fn set_settings(&self, settings: Settings)

Set the settings

fn waker(&self) -> &AtomicWaker

Returns the waker for the connection

impl<B, C> HandleDatagramsExt<C, B> for Connection<C, B>

where B: Buf, C: Connection<B> + DatagramConnectionExt<B>,

fn get_datagram_sender( &self, stream_id: StreamId, ) -> DatagramSender<<C as DatagramConnectionExt<B>>::SendDatagramHandler, B>

Sends a datagram

fn get_datagram_reader( &self, ) -> DatagramReader<<C as DatagramConnectionExt<B>>::RecvDatagramHandler>

Reads an incoming datagram