Trait Protocol 

pub trait Protocol<Rin, Win, Ein> {
    type Rout;
    type Wout;
    type Eout;
    type Error;

    // Required methods
    fn handle_read(&mut self, msg: Rin) -> Result<(), Self::Error>;
    fn poll_read(&mut self) -> Option<Self::Rout>;
    fn handle_write(&mut self, msg: Win) -> Result<(), Self::Error>;
    fn poll_write(&mut self) -> Option<Self::Wout>;

    // Provided methods
    fn handle_event(&mut self, _evt: Ein) -> Result<(), Self::Error> { ... }
    fn poll_event(&mut self) -> Option<Self::Eout> { ... }
    fn handle_timeout(&mut self, _now: Instant) -> Result<(), Self::Error> { ... }
    fn poll_timeout(&mut self) -> Option<Instant> { ... }
    fn close(&mut self) -> Result<(), Self::Error> { ... }
}

Protocol trait for Sans-IO protocol implementations A Sans-IO protocol abstraction.

The Protocol trait provides a simplified interface for building network protocols that are fully decoupled from I/O operations.

Type Parameters

• Rin: Input read message type
• Win: Input write message type
• Ein: Input event type

Design Pattern

This trait follows a push-pull pattern:

1. Push data/events into the protocol using handle_* methods
2. Pull results from the protocol using poll_* methods

This allows the protocol logic to be completely independent of I/O, making it easy to test and reuse in different contexts.

Example

See the module-level documentation for a complete example.

Required Associated Types

type Rout

Output read message type

This is the type of messages produced after processing inbound data.

type Wout

Output write message type

This is the type of messages produced for outbound transmission.

type Eout

Output event type

Custom events that the protocol may generate.

type Error

Error type for protocol operations

Required Methods

fn handle_read(&mut self, msg: Rin) -> Result<(), Self::Error>

Handle an incoming read message.

Processes an inbound message. The result can be polled later via poll_read.

Parameters

• msg: The incoming message to process

Returns

• Ok(()) if the message was successfully queued for processing
• Err(Self::Error) if processing failed

Example

protocol.handle_read(incoming_data)?;
// Later...
if let Some(processed) = protocol.poll_read() {
    // Handle processed data
}

fn poll_read(&mut self) -> Option<Self::Rout>

Poll for a processed read message.

Returns the next processed inbound message, if any. Call this after handle_read to retrieve processed results.

Returns

• Some(Rout) if a processed message is available
• None if no processed messages are ready

fn handle_write(&mut self, msg: Win) -> Result<(), Self::Error>

Handle an outgoing write message.

Processes an outbound message for transmission. The result can be polled later via poll_write.

Parameters

• msg: The outgoing message to process

Returns

• Ok(()) if the message was successfully queued
• Err(Self::Error) if processing failed

fn poll_write(&mut self) -> Option<Self::Wout>

Poll for a processed write message.

Returns the next processed outbound message, if any. Call this after handle_write to retrieve messages ready for transmission.

Returns

• Some(Wout) if a message is ready to send
• None if no messages are ready

Provided Methods

fn handle_event(&mut self, _evt: Ein) -> Result<(), Self::Error>

Handle a custom event.

Process protocol-specific events. The default implementation does nothing.

Parameters

• _evt: The event to handle

Returns

• Ok(()) by default
• Override to provide custom event handling logic

fn poll_event(&mut self) -> Option<Self::Eout>

Poll for a generated event.

Returns the next event generated by the protocol, if any.

Returns

• Some(Eout) if an event was generated
• None by default (override to implement custom events)

fn handle_timeout(&mut self, _now: Instant) -> Result<(), Self::Error>

Handle a timeout event.

Called periodically to allow the protocol to perform time-based operations (e.g., heartbeats, timeouts, retransmissions).

Parameters

• _now: The current timestamp

Returns

• Ok(()) by default
• Override to implement time-based protocol logic

fn poll_timeout(&mut self) -> Option<Instant>

Poll for the next timeout deadline.

Returns when the protocol next wants to be called via handle_timeout.

Returns

• Some(Instant) if the protocol has a pending timeout
• None if no timeout is needed (default)

Example

if let Some(deadline) = protocol.poll_timeout() {
    // Wait until deadline, then call protocol.handle_timeout(now)
}

fn close(&mut self) -> Result<(), Self::Error>

Close the protocol.

Called when the protocol should perform cleanup and release resources.

Returns

• Ok(()) by default
• Override to implement cleanup logic

Implementations on Foreign Types

impl<P, Rin, Win, Ein> Protocol<Rin, Win, Ein> for &mut P

where P: Protocol<Rin, Win, Ein> + ?Sized,

Blanket implementation for mutable references.

This allows protocols to be used through mutable references without requiring explicit dereferencing.

type Rout = <P as Protocol<Rin, Win, Ein>>::Rout

type Wout = <P as Protocol<Rin, Win, Ein>>::Wout

type Eout = <P as Protocol<Rin, Win, Ein>>::Eout

type Error = <P as Protocol<Rin, Win, Ein>>::Error

fn handle_read(&mut self, msg: Rin) -> Result<(), P::Error>

fn poll_read(&mut self) -> Option<P::Rout>

fn handle_write(&mut self, msg: Win) -> Result<(), P::Error>

fn poll_write(&mut self) -> Option<P::Wout>

fn handle_event(&mut self, evt: Ein) -> Result<(), P::Error>

fn poll_event(&mut self) -> Option<P::Eout>

fn handle_timeout(&mut self, now: Instant) -> Result<(), P::Error>

fn poll_timeout(&mut self) -> Option<Instant>

fn close(&mut self) -> Result<(), P::Error>

impl<P, Rin, Win, Ein> Protocol<Rin, Win, Ein> for Box<P>

where P: Protocol<Rin, Win, Ein> + ?Sized,

Blanket implementation for boxed protocols.

This allows protocols to be used through Box<dyn Protocol> for dynamic dispatch.

type Rout = <P as Protocol<Rin, Win, Ein>>::Rout

type Wout = <P as Protocol<Rin, Win, Ein>>::Wout

type Eout = <P as Protocol<Rin, Win, Ein>>::Eout

type Error = <P as Protocol<Rin, Win, Ein>>::Error

fn handle_read(&mut self, msg: Rin) -> Result<(), P::Error>

fn poll_read(&mut self) -> Option<P::Rout>

fn handle_write(&mut self, msg: Win) -> Result<(), P::Error>

fn poll_write(&mut self) -> Option<P::Wout>

fn handle_event(&mut self, evt: Ein) -> Result<(), P::Error>

fn poll_event(&mut self) -> Option<P::Eout>

fn handle_timeout(&mut self, now: Instant) -> Result<(), P::Error>

fn poll_timeout(&mut self) -> Option<Instant>

fn close(&mut self) -> Result<(), P::Error>

Implementors