Further describe the architecture

README.md

@@ -119,76 +119,89 @@ variables:
 
 I started this project because the alternatives were either unmaintained, not
 self-contained or very difficult to work with. With this implementation I'd like
-to prioritize maintainability and correctness, even if it would cause slightly
-more overhead than a more optimized solution would. Please let me know if you
-have any suggestions on how to improve this!
+to prioritize maintainability and correctness, with performance being a
+secondary goal. Please let me know if you have any suggestions on how to improve
+this!
 
 ## Architecture
 
 The project consists of two components, a Linux native VST plugin
 (`libyabridge.so`) and a VST host that runs under Wine
-(`yabridge-host.exe`/`yabridge-host.exe.so`). I'll refer to a copy or symlink of
-`libyabridge.so` as _the plugin_, the native Linux VST host that's hosting the
-plugin as _the native VST host_, the Wine VST host that's hosting a Windows
-`.dll` file as _the Wine VST host_, and the Windows VST plugin that's loaded in
-the Wine VST host is simply the _Windows VST plugin_. The whole process works as
-follows:
+(`yabridge-host.exe`/`yabridge-host.exe.so`). I'll refer to a copy of or a
+symlink to `libyabridge.so` as _the plugin_, the native Linux VST host that's
+hosting the plugin as _the native VST host_, the Wine VST host that's hosting a
+Windows `.dll` file as _the Wine VST host_, and the Windows VST plugin that's
+loaded in the Wine VST host is simply the _Windows VST plugin_. The whole
+process works as follows:
 
 1. Some copy of or a symlink to `libyabridge.so` gets loaded as a VST plugin in
    a Linux VST host. This file should have been renamed to match a Windows VST
    plugin `.dll` file in the same directory. For instance, if there's a
-   `Serum_x64.dll` file you'd like to bridge, then `libyabridge.so` should be
-   renamed to `Serum_x64.so`.
+   `Serum_x64.dll` file you'd like to bridge, then there should be a symlink to
+   `libyabridge.so` named `Serum_x64.so`.
 2. The plugin first attempts to locate:
 
    - The location of `yabridge-host.exe`. For this it will first search for the
-     file either alongside plugin. This is useful for development, as it allows
-     you to use a symlink to `libyabridge.so` from the build directory causing
-     yabridge to use the corresponding `yabridge-host.exe` from the same build
-     directory. If this file can't be found, it will fall back to searching
-     through the search path.
-   - The wine prefix plugin is located in
+     file either alongside `libyabridge.so`. This is useful for development, as
+     it allows you to use a symlink from the build directory to cause yabridge
+     to use the `yabridge-host.exe` from that same build directory. If this file
+     can't be found, then it will fall back to searching through the search path.
+   - The wine prefix plugin is located in.
    - The corresponding Windows VST plugin `.dll` file.
 
 3. The plugin then sets up a Unix domain socket endpoint to communicate with the
-   Wine VST host somewhere in a temporary directory. I chose to use Unix domain
-   sockets rather than shared memory to avoid having to do manual
-   synchronization and because they have very low overhead. This also makes it
-   possible to send arbitrarily large data without having to split it into
-   chunks first, which is useful for transmitting audio and preset data.
+   Wine VST host somewhere in a temporary directory and starts listening on it.
+   I chose to use Unix domain sockets rather than shared memory because this way
+   you get low latency communication with without any busy waits or manual
+   synchronisation for free. The added benefit is that it also makes it possible
+   to send arbitrarily large data without having to split it up into chunks
+   first, which is useful for transmitting audio and preset data which may have
+   any arbitrary size.
 4. The plugin launches the Wine VST host in the detected wine prefix, passing
    the name of the `.dll` file it should be loading and the path to the Unix
    domain socket that was just created.
 5. Communication gets set up using multiple sockets over the same end point.
-   This allows us to use blocking read operations while handling a certain event
-   type to avoid receiving messages out of order. The following types of events
-   get assigned a socket:
+   This allows us to use blocking read operations from multiple threads to
+   handle multiple different events without the risk of receiving packets in the
+   wrong order. The following types of events get assigned a socket:
 
    - Calls from the native VST host to the plugin's `dispatch()` function. These
      get forwarded to the Windows VST plugin through the Wine VST host.
    - Host callback calls from the Windows VST plugin loaded into the Wine VST
      host through the `audioMasterCallback` function. These get forwarded to the
      native VST host through the plugin.
+
+     Both the `dispatch()` and `audioMasterCallback()` functions are handled in
+     the same way, with some minor variations on how payload data gets
+     serialized depending on the opcode of the event being sent.
+
    - Calls from the native VST host to the plugin's `getParameter()` and
-     `setParameter()` functions. Both functions get forwarded to the Windows VST plugin
-     through the Wine VST host using a single socket.
+     `setParameter()` functions. Both functions get forwarded to the Windows VST
+     plugin through the Wine VST host using a single socket because they're very
+     similar and don't need any complicated behaviour.
    - Calls from the native VST host to the plugin's `process()` and
      `processReplacing()` functions. Both functions get forwarded to the Windows
-     VST plugin through the Wine VST host using a single socket.
+     VST plugin through the Wine VST host using a single socket. The `process()`
+     function has been deprecated, so a VST host will never call it if
+     `processReplacing()` is supported by the plugin.
+   - Updates of the Windows VST plugin's `AEffect` object. This object tells the
+     host about the plugin's capabilities. A copy of this is sent over a socket
+     from the Wine VST hsot to the plugin after it loads the Windows VST plugin
+     so it can return a pointer to it to the native VST host. Whenever this
+     struct updates, the Windows VST plugin will call the `audioMasterIOChanged`
+     host callback and we'll repeat this process.
 
-   The first step when passing through any of these function calls over a socket
-   is to serialize the function's parameters as binary data. Both request and
-   the corresponding response objects for all of these function calls can be
-   found in `src/common/communication.h`, along with functions to read and write
-   these objects over streams and sockets. The actual binary serialization is
-   handled using [bitsery](https://github.com/fraillt/bitsery).
+   The operations described above are all handled by first serializing the
+   function parameters and any payload into an object before they can be sent
+   over a socket. The objects used for encoding both the requests and and the
+   responses for theses events can be found in `src/common/communication.h`
+   along with functions that read and write these objects over streams and
+   sockets. The actual binary serialization is handled using
+   [bitsery](https://github.com/fraillt/bitsery).
 
 6. The Wine VST host loads the Windows VST plugin and starts forwarding messages
    over the sockets described above.
 7. After the Windows VST plugin has started loading we will forward all values
-   from the plugin's `AEffect` struct to the Linux native VST plugin. After this
-   point the plugin will stop blocking and has finished loading.
-
-   TODO: Do plugins update their `AEffect` struct update itself after
-   initialization? For instance to change the number of parameters. Is there any
-   way to catch this other than checking for updates ourselves?
+   from the plugin's `AEffect` struct to the Linux native VST plugin using the
+   socket described above. After this point the plugin will stop blocking and
+   has finished loading.