Struct tsyncp::util::stream_pool::StreamPool

pub struct StreamPool<S, const N: usize = 0> { /* private fields */ }

Pool of byte streams (i.e. TcpStream), which manages receiving and send to the underlying connections.

First generic parameter S is the type of the underlying byte stream, and const generic N is the number of streams when the pool uses an array instead of a vec. When vec is used, N defaults to 0.

The pool can be made of either a Vec of streams, or an array of streams. When it’s an array, it stores the streams in an array on the stack, which may allow better performance. Array’s length is the limit of total number of connections the pool can have, and current number of streams is kept as a field len. Unused array indices are placed as uninitialized MaybeUninit elements. This implementation does a careful job so that uninitialized memory is never accessed; however, I do understand that part of the safety concern of using uninitialized memory is that, in the future, I may forget what part of the code does what and accidently expose the unsafe code.

Therefore, if I find that using an array really has no effect on performance, I will remove the array implementation completely.

For streaming data from connections, the pool tries to poll every stream in the pool at every poll event. However, if one of the streams returns a result, it will save the last index of the stream it was polled, and start polling at the next index in the next poll event.

For sending data to connections, it tries to send to all connections even when encountering an error with some connections. So, it collects all the errors while sending data, and return them after data is flushed. When an error is encountered, the pool removes the errored stream from the pool, stores the error, then continues polling to the next stream.

Implementations

impl<S, const N: usize> StreamPool<S, N>

pub fn push_stream( &mut self, stream: S, addr: SocketAddr, ) -> Result<(), StreamPoolError>

Wrap the given byte stream into Framed, then push it into the pool.

impl<S, const N: usize> StreamPool<S, N>

pub fn is_array(&self) -> bool

Returns true is this pool uses an array to store streams.

pub fn is_vec(&self) -> bool

Returns true is this pool uses a Vec to store streams.

pub fn array<const M: usize>() -> StreamPool<S, M>

Returns pool with an array of streams with limit M.

Attempt to push a stream when the pool already has M streams will return an error.

pub fn vec() -> Self

Returns pool with a vec of streams with no limit or capacity.

pub fn with_capacity(capacity: usize) -> Self

Returns a pool with a vec of streams with a capacity but without limit.

pub fn with_limit(limit: usize) -> Self

Returns a pool with a vec of streams with a limit.

Attempt to push a stream when the pool already has already reached the limit will return an error.

pub fn len(&self) -> usize

Returns current number of streams in the pool.

pub fn limit(&self) -> Option<usize>

Returns total number of streams available in the pool.

pub fn addrs(&self) -> Vec<SocketAddr>

Returns remote addresses of all streams in the pool.

pub fn get(&self, index: usize) -> Option<&(Framed<S>, SocketAddr)>

Returns a reference of stream and address at the index.

pub fn get_mut(&mut self, index: usize) -> Option<&mut (Framed<S>, SocketAddr)>

Returns a mutable reference of stream and address at the index.

pub fn push( &mut self, stream: Framed<S>, addr: SocketAddr, ) -> Result<(), StreamPoolError>

Push a stream into the pool.

This will return an error if attempted to push a stream while pool is full.

pub fn pop(&mut self) -> Option<(Framed<S>, SocketAddr)>

Pops and returns a stream from the pool.

pub fn swap_remove(&mut self, index: usize) -> Option<(Framed<S>, SocketAddr)>

Swaps a stream at the index with the last element, and pops that element.

Trait Implementations

impl<S: Debug, const N: usize> Debug for StreamPool<S, N>

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

Formats the value using the given formatter.

impl<S: AsyncWrite + Unpin, const N: usize> Sink<Bytes> for StreamPool<S, N>

type Error = SinkErrors

The type of value produced by the sink when an error occurs.

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

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, item: Bytes) -> Result<(), Self::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

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

Flush any remaining output from this sink.

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

Flush any remaining output and close this sink, if necessary.

impl<S, const N: usize> Split for StreamPool<S, N>

where S: Split, S::Error: 'static,

Splits the pool into pool of read-only streams, and pool of write-only streams.

type Left = StreamPool<<S as Split>::Left, N>

Left half of split item

type Right = StreamPool<<S as Split>::Right, N>

Right half of split item

type Error = UnsplitError<<S as Split>::Error>

Error returned by associated method unsplit(_, _).

fn split(self) -> (Self::Left, Self::Right)

Split self into left and right halfs.

fn unsplit(r_half: Self::Left, w_half: Self::Right) -> Result<Self, Self::Error>

Unite left half and right half into Self again.

impl<S: AsyncRead + Unpin, const N: usize> Stream for StreamPool<S, N>

type Item = (Result<BytesMut, PollError>, SocketAddr)

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.