Do not thread by default, but let the user choose.

Issue-ID: RIC-228
Change-Id: Iab4acea6b235cdf5acf734b23b0aa735ee41e19c
Signed-off-by: Tommy Carpenter <tc677g@att.com>

diff --git a/docs/overview.rst b/docs/overview.rst
index 8071c9c..7a2a156 100644 (file)
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -37,7 +37,9 @@ 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.
+
 
 Examples
 --------

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 007a008..ec7f53d 100644 (file)
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -14,6 +14,12 @@ and this project adheres to `Semantic Versioning <http://semver.org/>`__.
    :depth: 3
    :local:
 
+[0.4.0] - 3/13/2020
+-------------------
+::
+
+    * minor breaking change; switches the default behavior RE threading for RMRXapps. The default is not to return execution, but the caller (in `run`) can choose to loop in a thread.
+
 
 [0.3.0] - 3/10/2020
 -------------------

diff --git a/examples/README.md b/examples/README.md
index 6677a18..1c1a6db 100644 (file)
--- a/examples/README.md
+++ b/examples/README.md
@@ -2,6 +2,8 @@
 
 Running the two examples (adjust for your shell notation)
 
+    pip install --user -e .
+    cd examples
     set -x LD_LIBRARY_PATH /usr/local/lib/:/usr/local/lib64; set -x  RMR_SEED_RT test_route.rt; python pong_xapp.py
-
+    (diff tmux window)
     set -x LD_LIBRARY_PATH /usr/local/lib/:/usr/local/lib64; set -x  RMR_SEED_RT test_route.rt; python ping_xapp.py

diff --git a/examples/pong_xapp.py b/examples/pong_xapp.py
index b19beec..ac72813 100644 (file)
--- a/examples/pong_xapp.py
+++ b/examples/pong_xapp.py
@@ -44,4 +44,4 @@ def defh(self, summary, sbuf):
 
 xapp = RMRXapp(default_handler=defh, post_init=post_init, use_fake_sdl=True)
 xapp.register_callback(sixtyh, 60000)
-xapp.run()
+xapp.run()  # will not thread by default

diff --git a/ricxappframe/xapp_frame.py b/ricxappframe/xapp_frame.py
index 6b70bb6..f278cf1 100644 (file)
--- a/ricxappframe/xapp_frame.py
+++ b/ricxappframe/xapp_frame.py
@@ -303,11 +303,16 @@ class RMRXapp(_BaseXapp):
         """
         self._dispatch[message_type] = handler
 
-    def run(self):
+    def run(self, thread=False):
         """
         This function should be called when the client xapp is ready to wait for their handlers to be called on received messages
 
-        execution is returned to caller
+        Parameters
+        ----------
+        thread: bool (optional)
+            if thread is True, execution is returned to caller and the queue read loop is executed in a thread.
+            The thread can be stopped using .stop()
+            if False, execution is not returned and the framework loops
         """
 
         def loop():
@@ -320,7 +325,10 @@ class RMRXapp(_BaseXapp):
                         func = self._default_handler
                     func(self, summary, sbuf)
 
-        Thread(target=loop).start()
+        if thread:
+            Thread(target=loop).start()
+        else:
+            loop()
 
     def stop(self):
         """

diff --git a/setup.py b/setup.py
index 6f6b36d..89872cd 100644 (file)
--- a/setup.py
+++ b/setup.py
@@ -32,7 +32,7 @@ def _long_descr():
 
 setup(
     name="ricxappframe",
-    version="0.3.0",
+    version="0.4.0",
     packages=find_packages(exclude=["tests.*", "tests"]),
     author="Tommy Carpenter",
     description="Xapp framework for python",

diff --git a/tests/test_init.py b/tests/test_init.py
index 1e05455..5aa6bf1 100644 (file)
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -57,6 +57,7 @@ def test_init_rmr_xapp():
         pass
 
     rmr_xapp = RMRXapp(foo, post_init=post_init, rmr_wait_for_ready=False, use_fake_sdl=True)
-    rmr_xapp.run()
+    # pytest will never return without thread and stop
+    rmr_xapp.run(thread=True)
     time.sleep(1)
-    rmr_xapp.stop()  # pytest will never return without this.
+    rmr_xapp.stop()

diff --git a/tests/test_xapps.py b/tests/test_xapps.py
index f80d375..37aebd1 100644 (file)
--- a/tests/test_xapps.py
+++ b/tests/test_xapps.py
@@ -50,7 +50,7 @@ def test_flow():
         self.rmr_free(sbuf)
 
     rmr_xapp.register_callback(sixtythou_handler, 60000)
-    rmr_xapp.run()
+    rmr_xapp.run(thread=True)  # in unit tests we need to thread here or else execution is not returned!
 
     time.sleep(1)