Struct TcpStream

pub struct TcpStream { /* private fields */ }

A TCP stream between a local and a remote socket, akin to std::net::TcpStream

All I/O operations provided by mtcp_rs::TcpStream are “blocking”, but – unlike the std::net implementation – proper timeout and cancellation support is available. The mtcp_rs::TcpStream is tied to an mtcp_rs::TcpManager instance.

The TCP stream is created by connect()ing to a remote host, or directly from() an existing mtcp_rs::TcpConnection.

If the timeout parameter was set to Some(Duration) and if the I/O operation does not complete before the specified timeout period expires, then the pending I/O operation will be aborted and fail with an TcpError::TimedOut error.

Functions like Read::read() and Write::write(), which do not have an explicit timeout parameter, implicitly use the timeouts that have been set up via the set_default_timeouts() function. Initially, these timeouts are disabled.

Implementations

impl TcpStream

pub fn from( manager: &Rc<TcpManager>, connection: TcpConnection, ) -> IoResult<Self>

Initialize a new TcpStream from an existing TcpConnection instance.

TcpConnection instances are usually obtained by accept()ing incoming TCP connections via a bound TcpListener.

The new TcpStream is tied to the specified TcpManager instance.

pub fn set_default_timeouts( &mut self, timeout_rd: Option<Duration>, timeout_wr: Option<Duration>, )

Set up the default timeouts, to be used by functions like Read::read() and Write::write().

pub fn peer_addr(&self) -> Option<SocketAddr>

Get the peer socket address of this TCP stream.

pub fn local_addr(&self) -> Option<SocketAddr>

Get the local socket address of this TCP stream.

pub fn shutdown(&self, how: Shutdown) -> IoResult<()>

Shuts down the read, write, or both halves of this TCP stream.

pub fn connect( manager: &Rc<TcpManager>, addr: SocketAddr, timeout: Option<Duration>, ) -> Result<Self, TcpError>

Opens a new TCP connection to the remote host at the specified address.

An optional timeout can be specified, after which the operation is going to fail, if the connection could not be established yet.

The new TcpStream is tied to the specified TcpManager instance.

pub fn read_timeout( &mut self, buffer: &mut [u8], timeout: Option<Duration>, ) -> Result<usize, TcpError>

Read the next “chunk” of incoming data from the TCP stream into the specified destination buffer.

This function attempts to read a maximum of buffer.len() bytes, but fewer bytes may actually be read! Specifically, the function waits until some data become available for reading, or the end of the stream (or an error) is encountered. It then reads as many bytes as are available and returns immediately. The function does not wait any longer, even if the buffer is not filled completely.

An optional timeout can be specified, after which the operation is going to fail, if still no data is available for reading.

Returns the number of bytes that have been pulled from the stream into the buffer, which is less than or equal to buffer.len(). A zero return value indicates the end of the stream. Otherwise, more data may become available for reading soon!

pub fn read_all_timeout<F>( &mut self, buffer: &mut Vec<u8>, timeout: Option<Duration>, chunk_size: Option<NonZeroUsize>, maximum_length: Option<NonZeroUsize>, fn_complete: F, ) -> Result<(), TcpError>

where F: Fn(&[u8]) -> bool,

Read all incoming data from the TCP stream into the specified destination buffer.

This function keeps on reading from the stream, until the input data has been read completely, as defined by the fn_complete closure, or an error is encountered. All input data is appended to the given buffer, extending the buffer as needed. The fn_complete closure is invoked every time that a new “chunk” of input was received. Unless the closure returned true, the function waits for more input. If the end of the stream is encountered while the data still is incomplete, the function fails.

The closure fn_complete takes a single parameter, a reference to the current buffer, which contains all data that has been read so far. That closure shall return true if and only if the data in the buffer is considered “complete”.

An optional timeout can be specified, after which the operation is going to fail, if the data still is not complete.

The optional chunk size specifies the maximum amount of data that can be read at once.

An optional maximum length can be specified. If the total size exceeds this limit before the data is complete, the function fails.

pub fn write_timeout( &mut self, buffer: &[u8], timeout: Option<Duration>, ) -> Result<usize, TcpError>

Write the next “chunk” of outgoing data from the specified source buffer to the TCP stream.

This function attempts to write a maximum of buffer.len() bytes, but fewer bytes may actually be written! Specifically, the function waits until some data can be written, the stream is closed by the peer, or an error is encountered. It then writes as many bytes as possible to the stream. The function does not wait any longer, even if not all data in buffer could be written yet.

An optional timeout can be specified, after which the operation is going to fail, if still no data could be written.

Returns the number of bytes that have been pushed from the buffer into the stream, which is less than or equal to buffer.len(). A zero return value indicates that the stream was closed. Otherwise, it may be possible to write more data soon!

pub fn write_all_timeout( &mut self, buffer: &[u8], timeout: Option<Duration>, ) -> Result<(), TcpError>

Write all outgoing data from the specified source buffer to the TCP stream.

This function keeps on writing to the stream, until the output data has been written completely, the peer closes the stream, or an error is encountered. If the stream is closed before all data could be written, the function fails.

An optional timeout can be specified, after which the operation is going to fail, if the data still was not written completely.

Trait Implementations

impl Debug for TcpStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for TcpStream

fn drop(&mut self)

Executes the destructor for this type.

impl Read for TcpStream

fn read(&mut self, buf: &mut [u8]) -> IoResult<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Write for TcpStream

fn write(&mut self, buf: &[u8]) -> IoResult<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> IoResult<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.