multiprocess: Add comments and documentation

2 files changed, 28 insertions, 3 deletions

diff --git a/src/interfaces/README.md b/src/interfaces/README.md
index f77d172153..97167d5298 100644
--- a/src/interfaces/README.md
+++ b/src/interfaces/README.md
@@ -12,6 +12,8 @@ The following interfaces are defined here:
 
 * [`Handler`](handler.h) — returned by `handleEvent` methods on interfaces above and used to manage lifetimes of event handlers.
 
-* [`Init`](init.h) — used by multiprocess code to access interfaces above on startup. Added in [#10102](https://github.com/bitcoin/bitcoin/pull/10102).
+* [`Init`](init.h) — used by multiprocess code to access interfaces above on startup. Added in [#19160](https://github.com/bitcoin/bitcoin/pull/19160).
 
-The interfaces above define boundaries between major components of bitcoin code (node, wallet, and gui), making it possible for them to run in different processes, and be tested, developed, and understood independently. These interfaces are not currently designed to be stable or to be used externally.
+* [`Ipc`](ipc.h) — used by multiprocess code to access `Init` interface across processes. Added in [#19160](https://github.com/bitcoin/bitcoin/pull/19160).
+
+The interfaces above define boundaries between major components of bitcoin code (node, wallet, and gui), making it possible for them to run in [different processes](../../doc/multiprocess.md), and be tested, developed, and understood independently. These interfaces are not currently designed to be stable or to be used externally.
diff --git a/src/interfaces/ipc.h b/src/interfaces/ipc.h
index 65df575da8..e9e6c78053 100644
--- a/src/interfaces/ipc.h
+++ b/src/interfaces/ipc.h
@@ -13,7 +13,30 @@ namespace interfaces {
 class Init;
 
 //! Interface providing access to interprocess-communication (IPC)
-//! functionality.
+//! functionality. The IPC implementation is responsible for establishing
+//! connections between a controlling process and a process being controlled.
+//! When a connection is established, the process being controlled returns an
+//! interfaces::Init pointer to the controlling process, which the controlling
+//! process can use to get access to other interfaces and functionality.
+//!
+//! When spawning a new process, the steps are:
+//!
+//! 1. The controlling process calls interfaces::Ipc::spawnProcess(), which
+//!    calls ipc::Process::spawn(), which spawns a new process and returns a
+//!    socketpair file descriptor for communicating with it.
+//!    interfaces::Ipc::spawnProcess() then calls ipc::Protocol::connect()
+//!    passing the socketpair descriptor, which returns a local proxy
+//!    interfaces::Init implementation calling remote interfaces::Init methods.
+//! 2. The spawned process calls interfaces::Ipc::startSpawnProcess(), which
+//!    calls ipc::Process::checkSpawned() to read command line arguments and
+//!    determine whether it is a spawned process and what socketpair file
+//!    descriptor it should use. It then calls ipc::Protocol::serve() to handle
+//!    incoming requests from the socketpair and invoke interfaces::Init
+//!    interface methods, and exit when the socket is closed.
+//! 3. The controlling process calls local proxy interfaces::Init object methods
+//!    to make other proxy objects calling other remote interfaces. It can also
+//!    destroy the initial interfaces::Init object to close the connection and
+//!    shut down the spawned process.
 class Ipc
 {
 public: