-Examples
---------
-There are two examples in the `examples` directory; `ping` which is a general Xapp, and `pong` which is an RMR Xapp.
-Ping sends a message, pong receives the message and use rts to reply.
-Ping then reads it's own mailbox and demonstrates other functionality.
-The highlight to note is that `pong` is purely reactive, it only does anything when a message is received.
-Ping uses a general that also happens to read it's rmr mailbox inside.
+A general Xapp acts according to its own criteria, which may include
+receipt of RMR messages.
+
+This type of application is constructed by creating a function that
+gets invoked by the framework. Typically that function contains a
+`while (something)` event loop. If the function returns, the Xapp
+stops. In this type of Xapp, the Xapp must fetch its own data, either
+from RMR, SDL or other source. The framework does less work for a
+general application compared to a reactive application. The framework
+sets up an RMR thread and an SDL connection, then invokes the
+client-provided function.
+
+Threading in the Framework
+--------------------------
+
+RMR interactions are processed in a thread started by the framework.
+This implementation detail is documented here for transparency, but
+most users will not have to worry about this.
+
+In both types of Xapp, the framework launches a separate thread whose
+only job is to read from RMR and deposit all messages (and their
+summaries) into a thread-safe queue. When the client Xapp reads from
+RMR using the framework (this read is done by the framework itself in
+the RMR Xapp, but by the client in a general Xapp), the read is done
+from the framework-managed queue. The framework is implemented this
+way so that a long-running client function (e.g., consume) will not
+block RMR reads. This is important because RMR is *not* a persistent
+message bus, if an RMR client does not read fast enough, messages can
+be lost. So in this framework the client code is not in the same
+thread as the RMR reads, to ensure that long-running client code will
+not cause message loss.