docs: improve local socket overview

This should hopefully make the "new" enum dispatch design less confusing
for those new to the crate.

Author: kotauskas

src/local_socket.rs

@@ -1,25 +1,73 @@
-//! 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.
+//! 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.
 //!
-//! ## 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.
+//! ## 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 IPC
+//! primitives are available on different platforms and have different capabilities and
+//! limitations. As such, the types representing local sockets that you can find 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`](traits::Listener), [`Stream`](traits::Stream)
+//! [`RecvHalf`](traits::RecvHalf), [`SendHalf`](traits::SendHalf) traits that you can find 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][udswnd]. Even then, the overhead of this
+//! dispatch is insignificant compared to the overhead of making the system calls that perform
+//! the actual communication.)
 //!
-//! 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](Name) and [name type](NameType) infrastructure.
+//! [udswnd]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/
 //!
-//! ## 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?
+//! 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, the mapping of local sockets to underlying primitives is stable and
+//! predictable. **The IPC primitive selected depends only on the current platform and the
+//! [name type](NameType) used.** The mapping is trivial unless noted otherwise (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), 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. All you need to do
+//! is use the correct name type for every platform.
+//!
+//! ## 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:
+//! ```no_run
+//! # #[cfg(unix)]
+//! use {interprocess::local_socket::prelude::*, std::os::unix::prelude::*};
+//! # #[cfg(unix)] fn hi(fd: OwnedFd, fd2: OwnedFd) {
+//!
+//! // Creating a stream from a file descriptor
+//! let stream = LocalSocketStream::UdSocket(fd.into());
+//! # let _ = stream;
+//!
+//! // Consuming a stream to get its file descriptor
+//! let fd = match stream {
+//!     LocalSocketStream::UdSocket(s) => OwnedFd::from(s),
+//! };
+//! # let _ = fd;
+//!
+//! # let stream = LocalSocketStream::UdSocket(fd2.into());
+//! // Accessing a stream's file descriptor without taking ownership
+//! let fd = match stream {
+//!     LocalSocketStream::UdSocket(s) => s.as_fd(),
+//! };
+//! # let _ = fd;
+//!
+//! // Listener, RecvHalf, and SendHalf work analogously.
+//! // Works just the same on Windows under the replacement of Fd with Handle.
+//! # }
+//! ```
 
 #[macro_use]
 mod enumdef;

src/local_socket/listener/enum.rs

@@ -15,15 +15,18 @@ mkenum!(
 ///
 /// This struct is created by [`ListenerOptions`](super::options::ListenerOptions).
 ///
+/// See the [module-level documentation](crate::local_socket) for more details.
+///
 /// # Name reclamation
 /// *This section only applies to Unix domain sockets.*
 ///
 /// When a Unix domain socket listener is closed, its associated socket file is not automatically
 /// deleted. Instead, it remains on the filesystem in a zombie state, neither accepting connections
 /// nor allowing a new listener to reuse it – [`create_sync()`] will return
-/// [`AddrInUse`](io::ErrorKind::AddrInUse) unless it is deleted manually.
+/// [`AddrInUse`](io::ErrorKind::AddrInUse) on some platforms unless the detached socket file is
+/// deleted manually.
 ///
-/// Interprocess implements *automatic name reclamation* via: when the local socket listener is
+/// Interprocess implements *automatic name reclamation*: when the local socket listener is
 /// dropped, it performs [`std::fs::remove_file()`] (i.e. `unlink()`) with the path that was
 /// originally passed to [`create_sync()`], allowing for subsequent reuse of the local socket name.
 ///

src/local_socket/stream/enum.rs

@@ -61,6 +61,8 @@ mkenum!(
 /// Local socket byte stream, obtained either from [`Listener`](super::super::Listener) or by
 /// connecting to an existing local socket.
 ///
+/// See the [module-level documentation](crate::local_socket) for more details.
+///
 /// # Examples
 ///
 /// ## Basic client
@@ -120,6 +122,8 @@ multimacro! {
 
 mkenum!(
 /// Receive half of a local socket stream, obtained by splitting a [`Stream`].
+///
+/// See the [module-level documentation](crate::local_socket) for more details.
 "local_socket::" RecvHalf);
 impl r#trait::RecvHalf for RecvHalf {
     type Stream = Stream;
@@ -128,6 +132,8 @@ dispatch_read!(RecvHalf);
 
 mkenum!(
 /// Send half of a local socket stream, obtained by splitting a [`Stream`].
+///
+/// See the [module-level documentation](crate::local_socket) for more details.
 "local_socket::" SendHalf);
 impl r#trait::SendHalf for SendHalf {
     type Stream = Stream;