Enum Stream 

pub enum Stream {
    UdSocket(Stream),
}

Available on crate feature tokio only.

Tokio-based local socket byte stream, obtained either from Listener or by connecting to an existing local socket.

See the module-level documentation of local sockets for more details.

Examples

Basic client

use {
   interprocess::local_socket::{
       tokio::{prelude::*, Stream},
       GenericNamespaced, ListenerOptions,
   },
   std::io,
   tokio::{
       io::{AsyncBufReadExt, AsyncWriteExt, BufReader},
       try_join,
   },
};

async fn handle_conn(conn: Stream) -> io::Result<()> {
   let mut recver = BufReader::new(&conn);
   let mut sender = &conn;

   let mut buffer = String::with_capacity(128);

   let send = sender.write_all(b"Hello from server!\n");
   let recv = recver.read_line(&mut buffer);

   try_join!(recv, send)?;

   // Avoid holding up resources.
   drop(conn);

   // read_line keeps the line feed at the end.
   print!("Client answered: {buffer}");
   Ok(())
}

let printname = "example.sock";
let name = printname.to_ns_name::<GenericNamespaced>()?;

let listener = match ListenerOptions::new().name(name).create_tokio() {
   Err(e) if e.kind() == io::ErrorKind::AddrInUse => {
       // When a program that uses a file-type socket name terminates
       // its socket server without deleting the file, a "corpse socket"
       // remains, which can neither be connected to nor reused by a new
       // listener. Normally, Interprocess takes care of this on affected
       // platforms by deleting the socket file when the listener is
       // dropped. (This is vulnerable to all sorts of races and thus can
       // be disabled.)
       //
       // In a real program, instead of leaving it up to the user
       // to perform cleanup, one would use the .try_overwrite(true)
       // listener option to try to replace the socket.
       eprintln!(
           "Error: could not start server because the socket file is \
           occupied. Please check if {printname} is in use by another \
           process and try again."
       );
       return Err(e.into());
   }
   x => x?,
};

// This is a good place to inform clients that the server is ready.
eprintln!("Server running at {printname}");

loop {
   let conn = match listener.accept().await {
       Ok(c) => c,
       Err(e) => {
           eprintln!("There was an error with an incoming connection: {e}");
           continue;
       }
   };

   // Spawn new parallel asynchronous tasks onto the Tokio runtime and
   // hand the connection over to them so that multiple clients could be
   // processed simultaneously in a lightweight fashion.
   tokio::spawn(async move {
       // The outer match processes errors that happen when we're
       // connecting to something. The inner if-let processes errors
       // that happen during the connection.
       if let Err(e) = handle_conn(conn).await {
           eprintln!("Error while handling connection: {e}");
       }
   });
}

Variants

UdSocket(Stream)

Available on Unix only.

Makes use of Unix domain sockets.

Click the struct name in the parentheses to learn more.

Trait Implementations

impl AsyncRead for &Stream

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

Attempts to read from the AsyncRead into buf.

impl AsyncRead for Stream

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

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for &Stream

Flushing and shutdown are always successful no-ops.

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

Attempt to write bytes from buf into the object.

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

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

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

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

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

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

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl AsyncWrite for Stream

Flushing and shutdown are always successful no-ops.

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

Attempt to write bytes from buf into the object.

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

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

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

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

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

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

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for Stream

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

Formats the value using the given formatter.

impl From<Stream> for Stream

Available on Unix only.

fn from(x: Stream) -> Self

Converts to this type from the input type.

impl Stream for Stream

type RecvHalf = RecvHalf

Receive half type returned by .split().

type SendHalf = SendHalf

Send half type returned by .split().

async fn from_options(options: &ConnectOptions<'_>) -> Result<Self>

Connects to a local socket server using the specified options.

fn split(self) -> (RecvHalf, SendHalf)

Splits a stream into a receive half and a send half.

fn reunite(rh: RecvHalf, sh: SendHalf) -> ReuniteResult

Attempts to reunite a receive half with a send half to yield the original stream back, returning both halves as an error if they belong to different streams.

fn connect(name: Name<'_>) -> impl Future<Output = Result<Self>> + Send + Sync

Asynchronously connects to a local socket server.

impl StreamCommon for Stream

fn take_error(&self) -> Result<Option<Error>>

Reads the stored error code from the socket, returning None if no error has happened since the last call to a method that propagates stored errors. Subsequent calls will return None until another error occurs.

fn peer_creds(&self) -> Result<PeerCreds>

Returns a structure containing a subset of the credentials of the other side of the connection. The nature of the credentials is OS-specific and using some of them for making security decisions may be subject to race conditions.