doc: Add internal design section #111

  10 | @@ -11,6 +11,16 @@ If the wrapped C++ object inherits from an abstract base class declaring virtual
  11 |  
  12 |  There is also optional support for thread mapping, so each thread making interprocess calls can have a dedicated thread processing requests from it, and callbacks from processing threads are executed on corresponding request threads (so recursive mutexes and thread names function as expected in callbacks).
  13 |  
  14 | +Libmultiprocess acts as a pure wrapper or layer over the underlying protocol. Clients and servers written in other languages, but using a shared capnproto schema can communicate with interprocess counterparties using libmultiprocess without having to use libmultiprocess themselves or having to know about the implementation details of libmultiprocess.
  15 | +
  16 | +### Internals
  17 | +
  18 | +The `ProxyClient` and `ProxyServer` generated classes are not directly exposed to the user, as described in [usage.md](usage.md). Instead, they wrap c++ interfaces and appear to the user as pointers to an interface. They are first instantiated when calling `ConnectStream` and `ServeStream` respectively for creating the `InitInterface`. These methods setup a `Connection` through a socket and wrap a `capnp::RpcSystem` configured for client and server mode respectively. Once more interfaces are instantiated from the `InitInterface`, they communicate over the same connection. Both `ConnectStream` and `ServerStream` also require an instantiation of the `EventLoop`. The `EventLoop` owns pending requests, notifies on request dispatch, allows clients from multiple threads to make synchronous calls, and handles some cleanup routines on exit. It must be run in a separate thread to allow calls being issued from multiple distinct threads.

---

  15 | +
  16 | +### Internals
  17 | +
  18 | +The `ProxyClient` and `ProxyServer` generated classes are not directly exposed to the user, as described in [usage.md](usage.md). Instead, they wrap c++ interfaces and appear to the user as pointers to an interface. They are first instantiated when calling `ConnectStream` and `ServeStream` respectively for creating the `InitInterface`. These methods setup a `Connection` through a socket and wrap a `capnp::RpcSystem` configured for client and server mode respectively. Once more interfaces are instantiated from the `InitInterface`, they communicate over the same connection. Both `ConnectStream` and `ServerStream` also require an instantiation of the `EventLoop`. The `EventLoop` owns pending requests, notifies on request dispatch, allows clients from multiple threads to make synchronous calls, and handles some cleanup routines on exit. It must be run in a separate thread to allow calls being issued from multiple distinct threads.
  19 | +
  20 | +When a generated method on the `ProxyClient` is called, it calls `clientInvoke` with the capnp-translated types. `clientInvoke` creates a self-executing promise (`kj::TaskSet`) that drives the execution of the request and gives ownership of it to the `EventLoop`.

---

  17 | +
  18 | +The `ProxyClient` and `ProxyServer` generated classes are not directly exposed to the user, as described in [usage.md](usage.md). Instead, they wrap c++ interfaces and appear to the user as pointers to an interface. They are first instantiated when calling `ConnectStream` and `ServeStream` respectively for creating the `InitInterface`. These methods setup a `Connection` through a socket and wrap a `capnp::RpcSystem` configured for client and server mode respectively. Once more interfaces are instantiated from the `InitInterface`, they communicate over the same connection. Both `ConnectStream` and `ServerStream` also require an instantiation of the `EventLoop`. The `EventLoop` owns pending requests, notifies on request dispatch, allows clients from multiple threads to make synchronous calls, and handles some cleanup routines on exit. It must be run in a separate thread to allow calls being issued from multiple distinct threads.
  19 | +
  20 | +When a generated method on the `ProxyClient` is called, it calls `clientInvoke` with the capnp-translated types. `clientInvoke` creates a self-executing promise (`kj::TaskSet`) that drives the execution of the request and gives ownership of it to the `EventLoop`.
  21 | +
  22 | +On the server side, the `capnp::RpcSystem` receives the capnp request and invokes the corresponding c++ method through the corresponding `ProxyServer` and the heavily templated `serverInvoke` triggering a `ServerCall`. Its result is then converted back by invoking `ServerRet`. The two are connected through `ServerField`. The main method driving execution of a request is `PassField`, which is invoked through `ServerField`. Instantiated interfaces, or capabilities in capnp speak, are tracked and owned by the server's `capnp::RpcSystem`.

---