Struct Context

Source

pub struct Context<Rin, Rout, Win, Wout> { /* private fields */ }

Expand description

Handler and context types for building protocol pipelines Enables a Handler to interact with the pipeline.

The Context object is passed to each handler method and provides the API for forwarding messages, polling data, and propagating events through the pipeline.

§Type Parameters

Rin: Read input message type (what the current handler receives)
Rout: Read output message type (what the current handler produces)
Win: Write input message type (what the current handler receives for writing)
Wout: Write output message type (what the current handler produces for writing)

§Responsibilities

The context provides two primary functions:

Forward Operations: Push data/events down the pipeline
- fire_handle_read(): Forward processed inbound messages
- fire_transport_active(): Propagate connection established event
- fire_handle_timeout(): Propagate timeout events
Pull Operations: Pull data from the next handler
- fire_poll_write(): Poll outbound messages from next handler
- fire_poll_timeout(): Poll timeout requirements from next handler

§Example

use sansio::{Handler, Context};

struct MyHandler;

impl Handler for MyHandler {
    type Rin = String;
    type Rout = String;
    type Win = String;
    type Wout = String;

    fn name(&self) -> &str {
        "MyHandler"
    }

    fn handle_read(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, msg: Self::Rin) {
        // Use context to forward message
        ctx.fire_handle_read(msg);
    }

    fn poll_write(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>) -> Option<Self::Wout> {
        // Use context to poll next handler
        ctx.fire_poll_write()
    }
}

Implementations§

Source §

impl<Rin: 'static, Rout: 'static, Win: 'static, Wout: 'static> Context<Rin, Rout, Win, Wout>

Source

pub fn new(name: &str) -> Self

Creates a new Context.

Typically called internally by the pipeline when adding a handler. You rarely need to create a Context manually.

§Parameters

name: The name of the handler this context belongs to

Source

pub fn fire_transport_active(&self)

Propagates transport active event to the next handler.

Call this to forward the “connection established” event through the pipeline. This should be called from your Handler::transport_active implementation unless you explicitly want to stop event propagation.

Source

pub fn fire_transport_inactive(&self)

Propagates transport inactive event to the next handler.

Call this to forward the “connection closed” event through the pipeline. This should be called from your Handler::transport_inactive implementation unless you explicitly want to stop event propagation.

Source

pub fn fire_handle_read(&self, msg: Rout)

Forwards an inbound message to the next handler.

After processing a message in Handler::handle_read, call this method to pass the transformed message (Rout) to the next handler in the pipeline.

§Parameters

msg: The processed message to forward

§Example

fn handle_read(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, msg: Self::Rin) {
    // Decode bytes to string
    if let Ok(decoded) = String::from_utf8(msg) {
        // Forward decoded message
        ctx.fire_handle_read(decoded);
    }
}

Source

pub fn fire_poll_write(&self) -> Option<Win>

Polls the next handler for an outbound message.

Call this from Handler::poll_write to retrieve messages from the next handler in the pipeline. Returns Some(Win) if the next handler has data to send, or None otherwise.

§Returns

Some(Win): A message from the next handler
None: No message available

§Example

fn poll_write(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>) -> Option<Self::Wout> {
    // Poll next handler first
    if let Some(msg) = ctx.fire_poll_write() {
        // Encode string to bytes
        return Some(msg.into_bytes());
    }
    // Then return our own queued data
    self.queue.pop_front()
}