refactor directory structure; add RTC wait on signal send

Author: wobrschalek

README.md

@@ -22,7 +22,7 @@ import logging
 import time
 
 import scxml4py.helper
-from scxml4py.engine import SCXML_Engine
+from scxmlApp.application import Application
 from scxml4py.action import Action
 from scxml4py.activity import ThreadedActivity
 from scxml4py.event import Event
@@ -70,7 +70,7 @@ simpleSM_string = '''<?xml version="1.0" ?>
 
 # SCXML source and data setup
 simple_sm_data = Data()
-simple_sm = SCXML_Engine(
+simple_sm = Application(
     simpleSM_string, 
     actions=[ActionStatus], 
     activities=[ActivityOnline], 
@@ -161,27 +161,27 @@ Visual SCXML Editor for VsCode: https://marketplace.visualstudio.com/items?itemN
 APACHE 2.0 License © 2024 Luigi Andolfato, Robert Karban
 
 
-## 📚 SCXML_Engine API
+## 📚 Application API
 
-The `SCXML_Engine` class provides a high-level API to load, execute, and interact with SCXML state machines.
+The `Application` class provides a high-level API to load, execute, and interact with SCXML state machines.
 
 ---
 
-### 🔹 `SCXML_Engine(scxml_doc: str, actions, activities, data)`
+### 🔹 `Application(scxml_doc: str, actions, activities, data)`
 
 #### **Constructor**
 Initializes the SCXML engine with a state machine definition and supporting elements.
 
 | Parameter     | Type      | Description |
 |---------------|-----------|-------------|
-| `scxml_doc`   | `str`     | The SCXML document as a string. |
+| `theScxmlDoc`   | `str`     | The SCXML document as a string. |
 | `actions`     | `list`    | List of `Action` classes to be instantiated and injected. |
 | `activities`  | `list`    | List of `Activity` classes to be instantiated and injected. |
 | `data`        | `Data`    | Shared data object passed to actions and activities. |
 
 #### **Example**
 ```python
-engine = SCXML_Engine(
+engine = Application(
     scxml_doc=some_scxml_string,
     actions=[ActionStatus],
     activities=[ActivityOnline],
@@ -304,7 +304,7 @@ class ActivityOnline(ThreadedActivity):
 Register the activity:
 
 ```python
-engine = SCXML_Engine(scxml_doc, actions=[], activities=[ActivityOnline], data=my_data)
+engine = Application(scxml_doc, actions=[], activities=[ActivityOnline], data=my_data)
 ```
 
 ---

src/scxml4py/__init__.py

@@ -11,4 +11,3 @@
 from .state import *
 from .stateMachine import *
 from .transition import *
-from .engine import *

src/scxml4py/event.py

@@ -49,8 +49,8 @@ def getId(self):
     def getType(self, theType):
         self.mType = theType
 
-    def getStatus(self, theStatus):
-        self.mStatus = theStatus
+    def getStatus(self):
+        return(self.mStatus)
 
     def setId(self, theId):
         self.mId = theId

src/scxmlApp/__init__.py

@@ -0,0 +1,2 @@
+from .application import Application
+from .actionmgr import ActionMgr

src/scxmlApp/actionmgr.py

@@ -0,0 +1,29 @@
+class ActionMgr(object):
+    # generated class    
+    def __init__(self):
+        self.mActionList = list()
+        self.mActivityList = list()
+
+    def getAction(self, theActionId):
+        for a in self.mActionList:
+            if a.getId() == theActionId:
+                return a
+        return None
+
+    def getActions(self):
+        return self.mActionList
+    
+    def getActivity(self, theActivityId):
+        for a in self.mActivityList:
+            if a.getId() == theActivityId:
+                return a
+        return None
+    
+    def getActivities(self):
+        return self.mActivityList
+    
+    def createActions(self, theData, action_classes):
+        self.mActionList = [cls(theData) for cls in action_classes]
+
+    def createActivities(self, theEventQueue, theData, activity_classes):
+        self.mActivityList = [cls(theEventQueue, theData) for cls in activity_classes]

src/scxmlApp/application.py

@@ -0,0 +1,125 @@
+import logging
+import threading
+from queue import Queue
+
+import scxml4py.helper
+from scxml4py.reader import Reader
+from scxml4py.context import Context
+from scxml4py.event import Event
+from scxml4py.executor import Executor
+from scxml4py.listeners import EventListener
+from scxml4py.action import Action
+from scxml4py.listeners import StatusListener
+
+from scxmlApp.actionmgr import ActionMgr
+
+# Installed as status listener, engine looks for "ActionStatus" action
+class _ActionStatus(Action, StatusListener):
+    # implemented by the developer, stub can be generated
+    def __init__(self, theData, theActionMgr):
+        Action.__init__(self, "ActionStatus", None, theData)
+        self.mStatus = None
+        self.mActionMgr = theActionMgr
+    
+    def notify(self, status):
+        self.mStatus = status
+        userActionStatus = self.mActionMgr.getAction("ActionStatusListener")
+        if userActionStatus is not None:
+            logging.getLogger("scxmlApp").debug (">>>>>>>>>>>>>>>>>>>>>>>>>>>userActionStatus found")    
+            userActionStatus.execute(status)
+        logging.getLogger("scxmlApp").info(">>>>_ActionStatus::notify Status: <" + scxml4py.helper.formatStatus(self.mStatus) + ">")
+    
+    # why do I need this?
+    def execute(self, theCtx):
+        logging.getLogger("scxmlApp").info(">>>>_ActionStatus::execute Status: <" + scxml4py.helper.formatStatus(self.mStatus) + ">")
+
+
+class _EventListener(EventListener):
+    def __init__(self, theData, callback, theActionMgr):
+        self.mEvent = None
+        self.callback = callback
+        self.theData = theData
+        self.mActionMgr = theActionMgr
+    
+    def notify(self, event):
+        self.mEvent = event
+        self.callback()
+        userActionEvent = self.mActionMgr.getAction("ActionEventListener")
+        if userActionEvent is not None:
+            logging.getLogger("scxmlApp").debug (">>>>>>>>>>>>>>>>>>>>>>>>>>>userActionEvent found")    
+            userActionEvent.execute(event)
+        logging.getLogger("scxmlApp").info(">>>>_EventListener::notify EventListener: <" + ">")
+        logging.getLogger("scxmlApp").debug(event.getStatus())
+
+
+class _Application(threading.Thread):   
+    def __init__(self, theScxmlDoc:str, data, theEventQueue, actions, activities):
+        threading.Thread.__init__(self)
+        self.mRunning = False
+        self.mEventQueue = theEventQueue
+        self.mData = data
+        self._event = threading.Event()
+        
+        self.mActionMgr = ActionMgr()
+        self.mActionMgr.createActions(theData=self.mData, action_classes=actions)
+        self.mActionMgr.createActivities(theEventQueue=self.mEventQueue, theData=self.mData, activity_classes=activities)
+        
+        self.mContext = Context()
+        logging.getLogger("scxmlApp").info("_Application::Loading SCXML model") 
+        self.mModel = Reader().readString("modelName", theScxmlDoc, self.mActionMgr.getActions(), self.mActionMgr.getActivities())
+        logging.getLogger("scxmlApp").debug("_Application::Loaded SCXML model: " + scxml4py.helper.formatModel(self.mModel))
+        self.mExecutor = Executor(self.mModel, self.mContext)
+        self.mActionStatus = _ActionStatus(theData=self.mData, theActionMgr = self.mActionMgr)
+        self.mEventListener = _EventListener(theData=self.mData, callback=self.event_callback, theActionMgr = self.mActionMgr)
+        self.mExecutor.addStatusListener(self.mActionStatus)
+        self.mExecutor.addEventListener(self.mEventListener)
+        logging.getLogger("scxmlApp").info("_Application::Status: <" + scxml4py.helper.formatStatus(self.mExecutor.getStatus()) + ">")
+        
+    def run(self):
+        logging.getLogger("scxmlApp").info("_Application::Starting execution of <" + self.mModel.getId() + ">")
+        self.mRunning = True
+        self.mExecutor.start()
+        logging.getLogger("scxmlApp").info("_Application::Status: <" + scxml4py.helper.formatStatus(self.mExecutor.getStatus()) + ">")
+        while self.mRunning == True:
+            theEvent = self.mEventQueue.get(True, None)
+            #Queue().get(block, timeout)
+            # loop on the event queue send the event to the SM engine
+            logging.getLogger("scxmlApp").debug("_Application::Application received event = <" + theEvent.__str__() + ">")
+            self.mExecutor.processEvent(theEvent)
+            if theEvent.getId() == "_EXIT":
+                logging.getLogger("scxmlApp").debug("_Application::Application exiting...")
+                self.mRunning = False
+        logging.getLogger("scxmlApp").info("_Application::Stopping execution of <" + self.mModel.getId() + ">")
+        self.mExecutor.stop()
+        logging.getLogger("scxmlApp").info("_Application::Status: <" + scxml4py.helper.formatStatus(self.mExecutor.getStatus()) + ">")
+
+    def event_callback(self):
+        self._event.set()  # unblock the waiting method
+
+    def wait_for_event(self):
+        self._event.wait()  # this blocks until .set() is called
+
+class Application:
+    def __init__(self, scxmlDoc: str, actions, activities, data):
+        self.doc = scxmlDoc
+        self.event_queue = Queue()
+        self.data = data
+
+        self.application = _Application(self.doc, self.data, self.event_queue, actions, activities)
+
+    def start(self):
+        self.application.start()
+
+    def terminate(self):
+        self.event_queue.put(Event("_EXIT"), True, 2)
+        self.application.wait_for_event()
+        self.application.join()
+
+    def get_current_status(self):
+        return scxml4py.helper.formatStatus(self.application.mExecutor.getStatus())
+
+    def send_signal(self, signal_name:str, sync:bool=True, rtc_block:bool=True):
+        self.event_queue.put(Event(signal_name), sync, 2)
+        if rtc_block:
+            self.application.wait_for_event()
+