Module local_socket 

Local sockets, a socket-like IPC primitive in which clients access a server through a filesystem path or an identifier inside a special namespace, with each client having a private connection to the server.

They are a much more appropriate alternative to localhost TCP sockets, featuring better performance and developer- and user-friendly identifiers and authentication.

Implementations and dispatch

Local sockets are not a real IPC primitive implemented by the OS, but rather a construct of Interprocess that is implemented in terms of an underlying IPC primitive. Different underlying IPC primitives are available on different platforms and have different capabilities and limitations. As such, the types representing local sockets that can be found in this module – Listener, Stream, RecvHalf, SendHalf – are really enums in the style of enum_dispatch that contain variants for all the different implementations of local sockets that are available, and the types that they dispatch between are talked to via the corresponding Listener, Stream RecvHalf, SendHalf traits that are located in the traits module.

Note that this dispatch is currently zero-cost on all platforms, as there is only one underlying local socket implementation per platform, with Windows only using named pipe based local sockets and Unix only using Unix-domain socket based local sockets, but this may change in the future with the introduction of support for the Windows implementation of Unix-domain sockets. Even if that were to be introduced, the overhead of dispatch would still be insignificant compared to the overhead of making the system calls that perform the actual communication.

The prelude module is there to make it easier to handle all of this complexity without suffering from naming collisions. use interprocess::local_socket::prelude::*; is the recommended way of bringing local sockets into scope.

Stability

Since interprocess communication cannot happen without agreement on a protocol between two or more processes, Interprocess provides a guarantee of stability of the mapping from local sockets to underlying primitives. The IPC primitive selected depends only on the current platform and the name type used. The mapping is trivial unless noted otherwise, which means that the portable API of local sockets is suitable for communicating with programs that do not use Interprocess themselves, including programs not written in Rust. In particular, Interprocess never inserts its own message framing or any other type of metadata into the stream – the bytes you write are the exact bytes that come out the other end. All you need to do to ensure reliable communication is use the appropriate name type on the platforms that are important to you.

Raw handle and file descriptor access

The enum dispatchers purposely omit implementations of {As,Into,From}Raw{Handle,Fd}, As{Handle,Fd}, From<Owned{HandleFd}> and Into<Owned{Handle,Fd}>. To access those trait implementations on the underlying implementation types, you need to match on the enum. For instance:

use {interprocess::local_socket::prelude::*, std::os::unix::prelude::*};

// Creating a stream from a file descriptor
let stream = LocalSocketStream::UdSocket(fd.into());

// Consuming a stream to get its file descriptor
let fd = match stream {
    LocalSocketStream::UdSocket(s) => OwnedFd::from(s),
};

// Accessing a stream's file descriptor without taking ownership
let stream_impl = match &stream {
    LocalSocketStream::UdSocket(s) => s,
};
let fd = stream_impl.as_fd();

// Listener, RecvHalf, and SendHalf work analogously.
// Works just the same on Windows under the replacement of Fd with Handle.

Modules

prelude

Re-exports of traits done in a way that doesn’t pollute the scope, as well as of the enum-dispatch types with their names prefixed with LocalSocket.

tokiotokio

Asynchronous local sockets which work with the Tokio runtime and event loop.

traits

Traits representing the interface of local sockets.

Structs

ConnectOptions

Client-side builder for local socket streams, including Stream.

Incoming

An infinite iterator over incoming client connections of a Listener.

ListenerOptions

Server-side builder for local socket listeners, including Listener.

Name

Name for a local socket.

PeerCreds

Credentials of a connection peer.

Enums

GenericFilePath

Consistent platform-specific mapping from filesystem paths to local socket names.

GenericNamespaced

Consistent platform-specific mapping from arbitrary OS strings to local socket names.

Listener

Local socket server, listening for connections.

ListenerNonblockingMode

The manner in which a listener is to be nonblocking.

RecvHalf

Receive half of a local socket stream, obtained by splitting a Stream.

SendHalf

Send half of a local socket stream, obtained by splitting a Stream.

Stream

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

Traits

NameType

Mappings from string types to local socket names.

NamespacedNameType

Mappings from strings to local socket names.

PathNameType

Mappings from paths to local socket names.

ToFsName

Conversion to a filesystem path-type local socket name.

ToNsName

Conversion to a namespaced local socket name.

Type Aliases

ReuniteError

ReuniteError for Stream.

ReuniteResult

Result type for .reunite() on Stream.