Struct WriteHalf

pub struct WriteHalf { /* private fields */ }

Write half of the WebSocket connection.

WriteHalf manages sending WebSocket frames and closing the connection gracefully. It handles:

• Compression of outgoing frames when enabled
• Masking of frames when acting as a client
• Protocol-compliant connection closure
• Frame buffering and flushing

Warning

In most cases, you should not use WriteHalf directly. Instead, use futures::StreamExt::split on the WebSocket to obtain stream halves that maintain all WebSocket protocol handling. Direct use of WriteHalf bypasses important protocol management like automatic control frame handling.

Connection Closure

When closing the connection, WriteHalf follows the WebSocket protocol by:

1. Sending a OpCode::Close frame to the peer
2. Flushing any pending frames
3. Closing the underlying network stream

This ensures a clean shutdown where all data is delivered before disconnection.

Example

use tokio::net::TcpStream;
use yawc::{WebSocket, frame::OpCode, Options, Result};
use futures::StreamExt;
use tokio_rustls::TlsConnector;

#[tokio::main]
async fn main() -> Result<()> {
    // Connect WebSocket
    let ws = WebSocket::connect("wss://example.com/ws".parse()?).await?;

    // Split into read/write halves
    let (stream, read_half, write_half) = unsafe { ws.split_stream() };
    // do something ...
    Ok(())
}

Implementations

impl WriteHalf

pub fn poll_ready<S>( &mut self, stream: &mut S, cx: &mut Context<'_>, ) -> Poll<Result<()>>

where S: Sink<Frame, Error = WebSocketError> + Unpin,

Polls the readiness of the WriteHalf to send a new frame.

If the WebSocket connection is already closed, this will return an error. Otherwise, it checks if the underlying stream is ready to accept a new frame.

Parameters

• stream: The WebSocket stream to check readiness on
• cx: The polling context

Returns

• Poll::Ready(Ok(())) if the WriteHalf is ready to send.
• Poll::Ready(Err(WebSocketError::ConnectionClosed)) if the connection is closed.

pub fn start_send<S>(&mut self, stream: &mut S, view: FrameView) -> Result<()>

where S: Sink<Frame, Error = WebSocketError> + Unpin,

Begins sending a frame through the WriteHalf.

This method takes a FrameView representing the frame to be sent and prepares it for transmission according to the WebSocket protocol rules:

• For non-control frames with compression enabled, the payload is compressed
• For client connections, the frame is automatically masked per protocol requirements
• Close frames trigger a state change to handle connection shutdown

The method handles frame preparation but does not wait for the actual transmission to complete. The prepared frame is queued for sending in the underlying stream.

Parameters

• stream: The WebSocket sink that will transmit the frame
• view: A FrameView containing the frame payload and metadata

Returns

• Ok(()) if the frame was successfully prepared and queued
• Err(WebSocketError) if frame preparation or queueing failed

Protocol Details

• Non-control frames are compressed if compression is enabled
• Client frames are masked per WebSocket protocol requirement
• Close frames transition the connection to closing state

pub fn poll_flush<S>( &mut self, stream: &mut S, cx: &mut Context<'_>, ) -> Poll<Result<()>>

where S: Sink<Frame, Error = WebSocketError> + Unpin,

Polls to flush all pending frames in the WriteHalf.

Ensures that any frames waiting to be sent are fully flushed to the network.

Parameters

• stream: The WebSocket stream to flush frames on
• cx: The polling context

Returns

• Poll::Ready(Ok(())) if all pending frames have been flushed.
• Poll::Pending if there are still frames waiting to be flushed.

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

where S: Sink<Frame, Error = WebSocketError> + Unpin,

Polls the connection to close the WriteHalf by initiating a graceful shutdown.

The poll_close function guides the closure process through several stages:

1. Sending: Sends a Close frame to the peer.
2. Flushing: Ensures the Close frame and any pending frames are fully flushed.
3. Closing: Closes the underlying network stream once the frames are flushed.
4. Done: Marks the connection as closed.

This sequence ensures a clean shutdown, allowing all necessary data to be sent before the connection closes.

Parameters

• stream: The WebSocket stream to close
• cx: The polling context

Returns

• Poll::Ready(Ok(())) once the connection is fully closed.
• Poll::Pending if the closure is still in progress.