Module local_socket

Local sockets, an IPC primitive featuring a server and multiple clients connecting to that server using a filesystem path or an identifier inside a special namespace, each having a private connection to that server.

Implementation types

Local sockets are not a real IPC method implemented by the OS – they exist to paper over the differences between the two underlying implementations currently in use: Unix domain sockets and Windows named pipes.

Interprocess defines traits that implementations of local sockets implement, and enums that constitute devirtualized trait objects (not unlike those provided by the enum_dispatch crate) for those traits. The implementation used, in cases where multiple options apply, is chosen at construction via the name and name type infrastructure.

Differences from regular sockets

A few missing features, primarily on Windows, require local sockets to omit some important functionality, because code relying on it wouldn’t be portable. Some notable differences are:

• No .shutdown() – your communication protocol must manually negotiate end of transmission. Notably, .read_to_string() and .read_all() will always block indefinitely at some point.
• No datagram sockets – the difference in semantics between connectionless datagram Unix-domain sockets and connection-based named message pipes on Windows does not allow bridging those two into a common API. You can emulate datagrams on top of streams anyway, so no big deal, right?

Re-exports

pub use traits::ListenerNonblockingMode;

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

Incoming

An infinite iterator over incoming client connections of a Listener.

ListenerOptions

A builder for local socket listeners, including Listener.

Name

Name for a local socket.

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.

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.