Struct SimTcpStream 

pub struct SimTcpStream { /* private fields */ }

Simulated TCP stream that implements async read/write operations.

SimTcpStream provides a realistic simulation of TCP socket behavior by implementing the AsyncRead and AsyncWrite traits. It interfaces with the simulation event system to provide ordered, reliable data delivery with configurable network delays.

Architecture Overview

Each SimTcpStream represents one endpoint of a TCP connection:

Application Layer          SimTcpStream Layer          Simulation Layer
─────────────────          ──────────────────          ─────────────────
                                                        
stream.write_all(data) ──► poll_write(data) ────────► buffer_send(data)
                                                       └─► ProcessSendBuffer event
                                                           └─► DataDelivery event
                                                               └─► paired connection
                                                        
stream.read(buf) ◄────── poll_read(buf) ◄──────────── receive_buffer
                         │                           └─► waker registration
                         └─► Poll::Pending/Ready     

TCP Semantics Implemented

This implementation provides the core TCP guarantees required for realistic simulation:

1. Reliable Delivery

• All written data will eventually be delivered to the paired connection
• No data loss (unless explicitly simulated via fault injection)
• Delivery confirmation through the event system

2. Ordered Delivery (FIFO)

• Messages written first will arrive first at the destination
• Achieved through per-connection send buffering
• Critical for protocols that depend on message ordering

3. Flow Control Simulation

• Read operations block (Poll::Pending) when no data is available
• Write operations complete immediately (buffering model)
• Backpressure handled at the application layer

Usage Examples

Provides async read/write operations for client and server connections.

Performance Characteristics

• Write Latency: O(1) - writes are buffered immediately
• Read Latency: O(network_delay) - depends on simulation configuration
• Memory Usage: O(buffered_data) - proportional to unread data
• CPU Overhead: Minimal - leverages efficient event system

Connection Lifecycle

1. Creation: Stream created with reference to simulation and connection ID
2. Active Phase: Read/write operations interact with simulation buffers
3. Data Transfer: Asynchronous event processing handles network simulation
4. Termination: Stream dropped when connection ends (automatic cleanup)

Thread Safety

SimTcpStream is Send + Sync + Unpin + 'static via its Arc<RwLock<…>> backed WeakSimWorld handle. The simulation runtime itself runs on a single OS thread (new_current_thread().build()), but the stream type satisfies Send-bounded traits so it composes naturally with tokio::spawn, hyper/reqwest connectors, and customer code that uses Arc<RwLock<…>> / DashMap / Arc<AtomicBool>.

Implementations

impl SimTcpStream

pub fn connection_id(&self) -> ConnectionId

Get the connection ID (for test introspection and chaos injection)

pub fn is_write_vectored(&self) -> bool

Returns true: SimTcpStream implements an efficient vectored write that records each IoSlice as its own ordered delivery event, so the chaos pack can act on individual segments.

Trait Implementations

impl AsyncRead for SimTcpStream

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncWrite for SimTcpStream

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush( self: Pin<&mut Self>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close( self: Pin<&mut Self>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempt to close the object.

impl Drop for SimTcpStream

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.