interprocess/local_socket/stream/
trait.rs

1#![allow(private_bounds)]
2
3use {
4    crate::{
5        bound_util::{RefRead, RefWrite},
6        local_socket::Name,
7        Sealed,
8    },
9    std::io::{self, prelude::*},
10};
11
12/// Local socket stream implementations.
13///
14/// Types on which this trait is implemented are variants of the
15/// [`Stream` enum](super::enum::Stream). In addition, it is implemented on `Stream` itself, which
16/// makes it a trait object of sorts. See its documentation for more on the semantics of the methods
17/// seen here.
18pub trait Stream: Read + RefRead + Write + RefWrite + Send + Sync + Sized + Sealed {
19    /// Receive half type returned by [`.split()`](Stream::split).
20    type RecvHalf: RecvHalf<Stream = Self>;
21    /// Send half type returned by [`.split()`](Stream::split).
22    type SendHalf: SendHalf<Stream = Self>;
23
24    /// Connects to a remote local socket server.
25    fn connect(name: Name<'_>) -> io::Result<Self>;
26
27    /// Enables or disables the nonblocking mode for the stream. By default, it is disabled.
28    ///
29    /// In nonblocking mode, receiving and sending immediately returns with the
30    /// [`WouldBlock`](io::ErrorKind::WouldBlock) error in situations when they would normally block
31    /// for an uncontrolled amount of time. The specific situations are:
32    /// - Receiving is attempted and there is no new data available;
33    /// - Sending is attempted and the buffer is full due to the other side not yet having
34    ///   received previously sent data.
35    fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()>;
36
37    /// Splits a stream into a receive half and a send half, which can be used to receive from and
38    /// send to the stream concurrently from different threads, entailing a memory allocation.
39    fn split(self) -> (Self::RecvHalf, Self::SendHalf);
40
41    /// Attempts to reunite a receive half with a send half to yield the original stream back,
42    /// returning both halves as an error if they belong to different streams (or when using this
43    /// method on streams that haven't been split to begin with).
44    fn reunite(rh: Self::RecvHalf, sh: Self::SendHalf) -> ReuniteResult<Self>;
45
46    // Do not add methods to this trait that aren't directly tied to non-async streams. A new trait,
47    // which should be called StreamExtra or StreamCommon or something along those lines, is to be
48    // created for features like impersonation (ones that are instantaneous in nature).
49}
50
51/// Receive halves of [`Stream`]s, obtained through [`.split()`](Stream::split).
52///
53/// Types on which this trait is implemented are variants of the
54/// [`RecvHalf` enum](super::enum::RecvHalf). In addition, it is implemented on `RecvHalf` itself,
55/// which makes it a trait object of sorts.
56pub trait RecvHalf: Sized + Read + RefRead + Sealed {
57    /// The stream type the half is split from.
58    type Stream: Stream;
59}
60
61/// Send halves of [`Stream`]s, obtained through [`.split()`](Stream::split).
62///
63/// Types on which this trait is implemented are variants of the
64/// [`SendHalf` enum](super::enum::SendHalf). In addition, it is implemented on `SendHalf` itself,
65/// which makes it a trait object of sorts.
66pub trait SendHalf: Sized + Write + RefWrite + Sealed {
67    /// The stream type the half is split from.
68    type Stream: Stream;
69}
70
71/// [`ReuniteResult`](crate::error::ReuniteResult) for the [`Stream` trait](Stream).
72pub type ReuniteResult<S> =
73    crate::error::ReuniteResult<S, <S as Stream>::RecvHalf, <S as Stream>::SendHalf>;
interprocess/local_socket/stream/trait.rs

interprocess/local_socket/stream/
trait.rs
