Module interprocess::local_socket

Local sockets, an IPC primitive featuring a server and multiple clients connecting to that server using a filesystem path 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.