Trait Protocol 

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

    // 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: Self::Time) -> Result<(), Self::Error> { ... }
    fn poll_timeout(&mut self) -> Option<Self::Time> { ... }
    fn close(&mut self) -> Result<(), Self::Error> { ... }
}

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

Associated Types

• Rout: Output read message type
• Wout: Output write message type
• Eout: Output event type
• Error: Error type for operations
• Time: Time/instant type for timeout handling

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

type Time

Time/Instant type for timeout handling

This type represents time instants for timeout handling.

• With std: Typically std::time::Instant
• Without std: Can be u64 (ticks), i64 (milliseconds), or any custom type

Examples

// With std
type Time = std::time::Instant;

// Without std (using tick counts)
type Time = u64;

// Without std (using milliseconds since epoch)
type Time = i64;

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: Self::Time) -> 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 time value (type specified by Self::Time)

Returns

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

Examples

With std:

fn handle_timeout(&mut self, now: std::time::Instant) -> Result<(), Self::Error> {
    // Check for expired connections, send heartbeats, etc.
    Ok(())
}

Without std (using tick counts):

fn handle_timeout(&mut self, now: u64) -> Result<(), Self::Error> {
    // now is in system ticks
    Ok(())
}

fn poll_timeout(&mut self) -> Option<Self::Time>

Poll for the next timeout deadline.

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

Returns

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

Examples

With std:

fn poll_timeout(&mut self) -> Option<std::time::Instant> {
    self.next_deadline
}

Without std (using tick counts):

fn poll_timeout(&mut self) -> Option<u64> {
    self.next_tick
}

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

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

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: P::Time) -> Result<(), P::Error>

fn poll_timeout(&mut self) -> Option<P::Time>

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

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

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: P::Time) -> Result<(), P::Error>

fn poll_timeout(&mut self) -> Option<P::Time>

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

Implementors