Block on RMR read to avoid 100% CPU usage on wait

[ric-plt/xapp-frame-py.git] / docs / overview.rst

diff --git a/docs/overview.rst b/docs/overview.rst
index 8071c9c..ffac38f 100644 (file)
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -2,8 +2,8 @@
 .. SPDX-License-Identifier: CC-BY-4.0
 .. Copyright (C) 2020 AT&T Intellectual Property
 
-xapp-frame-py Overview
-======================
+Framework Overview
+==================
 
 This library is a framework for writing Xapps in python.
 There may or may not be many Xapps written in python; however rmr, sdl, and logging libraries all exist for python, and this framework brings them together.
@@ -37,7 +37,19 @@ The framework is implemented this way so that a long running client function (e.
 This is important because rmr is *not* a persistent message bus, if any 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, so that long running client code can never lead to lost messages.
 
-In the case of RMR Xapps, there are currently 3 total threads; the thread that reads from rmr directly, the thread that reads from the queue and invokes the client callback, and the user thread. Running the xapp returns to the user and runs until the user calls `stop`.
+In the case of RMR Xapps, there are currently 3 potential threads; the thread that reads from rmr directly, and the user can optionally have the rmr queue read run in a thread, returning execution back to the user thread.
+The default is only two threads however, where `.run` does not return back execution and the user code is "finished" at that point.
+
+Healthchecks
+------------
+RMRXapps come with a default rmr healthcheck probe handler.
+When the RMRXapp is sent an rmr healthcheck, it will check to see if the rmr thread is healthy (well it can't even reply if it's not!), and that the SDL connection is healthy.
+The Xapp responds accordingly.
+The user can override this default handler by registering a new callback to the appropriate message type.
+
+General Xapps must handle healthchecks when they read their rmr mailbox, since there is no notion of handlers.
+
+There is no http service (Currently) in the framework therefore there are no http healthchecks.
 
 Examples
 --------
@@ -46,10 +58,3 @@ 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.
-
-Current gaps
-------------
-The following are known gaps or potential enhancements at the time of writing.
-::
-
-    * a logger has to be provided to the xapp