doc fixes

Author: jimblandy

wgpu-remote/src/transport/mod.rs

@@ -2,14 +2,28 @@
 
 This module defines the [`Sender`] and [`Receiver`] traits, representing the
 endpoints of a one-way communications channel between a wgpu client and server.
-A single `Sender` sends messages to a single `Receiver`. The two sides use
-shared memory segments to hold message content and other common data. Remote
-wgpu access requires two `Sender`/`Receiver` pairs, providing communication in
-each direction between client and server. This documentation refers to an
-interacting client and server as "counterparts".
+A single `Sender` sends messages to a single `Receiver`. A `Sender` can also
+create memory segments shared with the `Receiver` to hold message content and
+other common data.
+
+Remote wgpu access requires two `Sender`/`Receiver` pairs, providing
+communication in each direction between client and server. This documentation
+refers to an interacting client and server as "counterparts".
+
+`Sender` and `Receiver` are low-level traits. Using them entails working with
+raw pointers to shared memory segments, so applications will generally need to
+build higher-level abstractions around them them to provide well-typed
+interfaces, prevent data races, batch messages to reduce IPC overhead, and so
+on.
+
+## Senders
 
-`Sender` and `Receiver` are low-level traits, meant to be easy to implement in
-terms of a wide range of operating system mechanisms:
+A [`Sender`] implementation is responsible for interacting with the operating
+system to create memory segments that are shared with the `Receiver`, and
+sending unbuffered messages to the `Receiver`. However, a `Sender` should be
+agnostic to the actual content of those memory segments and messages. The
+`Sender` trait is meant to be easy to implement in terms of a wide range of
+operating system mechanisms:
 
 - A Unix implementation might use [`mmap`] to create memory segments, and then
   send `SCM_RIGHTS` messages over [`AF_UNIX`] sockets to share them with their
@@ -18,9 +32,21 @@ terms of a wide range of operating system mechanisms:
 - A Windows implementation might use [`CreateFileMappingW`] to create memory
   segments, and then use [`DuplicateHandle`] to share them.
 
-- For testing, the [`local]` module this crate provides a [`Sender`]
-  implementation in which both sides of the connection live in the same process.
-  "Shared" memory is simply an ordinary block of memory.
+- For testing, the [`transport::local`] module provides a [`Sender`]
+  implementation in which both sides of the connection live in the
+  same process. "Shared" memory is simply an ordinary block of memory.
+
+## Receivers
+
+The [`Receiver`] trait is meant to be implemented by users of the transport,
+serving as the callback invoked when messages are received. Exactly how
+`Receiver`s get called is specific to the `Sender` implementation:
+
+- A `Sender` implementation might spawn a thread to read messages from a socket
+  and invoke the `Receiver` when a complete message has been received.
+
+- A `Sender` implementation might register a listener with some sort of platform
+  event loop, and have that listener call the `Receiver` when appropriate.
 
 The [`Sender`] and [`Receiver`] traits are meant to integrate smoothly with
 existing interprocess communication mechanisms and event loops, like Firefox's
@@ -84,6 +110,7 @@ for the purposes of avoiding data races.
 [`AF_UNIX`]: https://man7.org/linux/man-pages/man7/unix.7.html
 [`CreateFileMappingW`]: https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-createfilemappingw
 [`DuplicateHandle`]: https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-duplicatehandle
+[`transport::local`]: crate::transport::local
 [`IPDL`]: https://firefox-source-docs.mozilla.org/ipc/ipdl.html
 [`nsISerialEventTarget`]: https://searchfox.org/mozilla-central/rev/7f7e8f6e4b8e09b145d29a57a1b341c6b11f4225/xpcom/threads/nsISerialEventTarget.idl#25
 [`flush_shared_memory_range`]: Sender::flush_shared_memory_range
@@ -179,8 +206,13 @@ pub trait Sender {
     /// The exact interpretation of `range` is entirely up to the user of the
     /// transport. In typical use, `range` refers to a byte range of `handle`
     /// that holds serialized messages of some sort, but the transport itself
-    /// doesn't assume that. Shared memory handles are  meant to be conveyed
-    /// by serializing them the content of messages
+    /// doesn't assume that.
+    ///
+    /// Since shared memory handles are ordinary integers and are automatically
+    /// usable in both counterparts, handles other than `handle` itself can be
+    /// conveyed to the counterpart simply by serializing them in the content of
+    /// messages, or storing them in other shared memory segments where the
+    /// counterpart can find them.
     ///
     /// [`receive_message`]: Receiver::receive_message
     fn send_message(