feat: Add queued mode (Support for RTC by default) (#359)

feat: Add rtc mode as default. Closes #80

Author: fgmacedo

docs/index.md

@@ -16,6 +16,7 @@ observers
 mixins
 integrations
 diagram
+processing_model
 auto_examples/index
 contributing
 authors

docs/processing_model.md

@@ -0,0 +1,134 @@
+# Processing model
+
+In the literature, It's expected that all state-machine events should execute on a
+[run-to-completion](https://en.wikipedia.org/wiki/UML_state_machine#Run-to-completion_execution_model)
+(RTC) model.
+
+> All state machine formalisms, including UML state machines, universally assume that a state machine
+> completes processing of each event before it can start processing the next event. This model of
+> execution is called run to completion, or RTC.
+
+The main point is: What should happen if the state machine triggers nested events while processing a parent event?
+
+```{hint}
+The importance of this decision depends on your state machine definition. Also the difference between RTC
+and non-RTC processing models is more pronounced in a multi-threaded system than in a single-threaded system.
+In other words, even if you run in {ref}`Non-RTC model`, only one external {ref}`event` will be
+handled at a time and all internal events will run before the next external event is called,
+so you only notice the difference if your state machine definition has nested event triggers while
+processing these external events.
+```
+
+There are two distinct models for processing events in the library. The default is to run in
+{ref}`RTC model` to be compliant with the specs, where the {ref}`event` is put on a
+queue before processing. You can also configure your state machine to run in
+{ref}`Non-RTC model`, where the {ref}`event` will be run immediately.
+
+Consider this state machine:
+
+```py
+>>> from statemachine import StateMachine, State
+
+>>> class ServerConnection(StateMachine):
+...     disconnected = State(initial=True)
+...     connecting = State()
+...     connected = State()
+...
+...     connect = disconnected.to(connecting, after="connection_succeed")
+...     connection_succeed = connecting.to(connected)
+...
+...     def on_connect(self):
+...         return "on_connect"
+...
+...     def on_enter_state(self, event: str, state: State, source: State):
+...         print(f"enter '{state.id}' from '{source.id if source else ''}' given '{event}'")
+...
+...     def on_exit_state(self, event: str, state: State, target: State):
+...         print(f"exit '{state.id}' to '{target.id}' given '{event}'")
+...
+...     def on_transition(self, event: str, source: State, target: State):
+...         print(f"on '{event}' from '{source.id}' to '{target.id}'")
+...         return "on_transition"
+...
+...     def after_transition(self, event: str, source: State, target: State):
+...         print(f"after '{event}' from '{source.id}' to '{target.id}'")
+...         return "after_transition"
+
+```
+
+## RTC model
+
+In a run-to-completion (RTC) processing model (**default**), the state machine executes each event to completion before processing the next event. This means that the state machine completes all the actions associated with an event before moving on to the next event. This guarantees that the system is always in a consistent state.
+
+If the machine is in `rtc` mode, the event is put on a queue.
+
+```{note}
+While processing the queue items, if others events are generated, they will be processed sequentially.
+```
+
+Running the above state machine will give these results on the RTC model:
+
+```py
+>>> sm = ServerConnection()
+enter 'disconnected' from '' given '__initial__'
+
+>>> sm.send("connect")
+exit 'disconnected' to 'connecting' given 'connect'
+on 'connect' from 'disconnected' to 'connecting'
+enter 'connecting' from 'disconnected' given 'connect'
+after 'connect' from 'disconnected' to 'connecting'
+exit 'connecting' to 'connected' given 'connection_succeed'
+on 'connection_succeed' from 'connecting' to 'connected'
+enter 'connected' from 'connecting' given 'connection_succeed'
+after 'connection_succeed' from 'connecting' to 'connected'
+['on_transition', 'on_connect']
+
+```
+
+```{note}
+Note that the events `connect` and `connection_succeed` are executed sequentially, and the `connect.after` runs on the expected order.
+```
+
+## Non-RTC model
+
+In contrast, in a non-RTC (synchronous) processing model, the state machine starts executing nested events
+while processing a parent event. This means that when an event is triggered, the state machine
+chains the processing when another event was triggered as a result of the first event.
+
+```{warning}
+This can lead to complex and unpredictable behavior in the system if your state-machine definition triggers **nested
+events**.
+```
+
+If your state machine does not trigger nested events while processing a parent event,
+and you plan to use the API in an _imperative programming style_, you can consider using the synchronous mode (non-RTC).
+
+In this model, you can think of events as analogous to simple method calls.
+
+```{note}
+While processing the {ref}`event`, if others events are generated, they will also be processed immediately, so a **nested** behavior happens.
+```
+
+Running the above state machine will give these results on the non-RTC (synchronous) model:
+
+```py
+>>> sm = ServerConnection(rtc=False)
+enter 'disconnected' from '' given '__initial__'
+
+>>> sm.send("connect")
+exit 'disconnected' to 'connecting' given 'connect'
+on 'connect' from 'disconnected' to 'connecting'
+enter 'connecting' from 'disconnected' given 'connect'
+exit 'connecting' to 'connected' given 'connection_succeed'
+on 'connection_succeed' from 'connecting' to 'connected'
+enter 'connected' from 'connecting' given 'connection_succeed'
+after 'connection_succeed' from 'connecting' to 'connected'
+after 'connect' from 'disconnected' to 'connecting'
+['on_transition', 'on_connect']
+
+```
+
+```{note}
+Note that the events `connect` and `connection_succeed` are nested, and the `connect.after`
+unexpectedly only runs after `connection_succeed.after`.
+```

docs/releases/1.0.1.md

@@ -7,7 +7,7 @@ Welcome to StateMachine 1.0.1!
 This version is a huge refactoring adding a lot of new and exciting features. We hope that you enjoy it.
 
 These release notes cover the [new features in 1.0](#whats-new-in-10), as well as
-some [backwards incompatible changes](#backwards-incompatible-changes-in-10) you'll
+some [backward incompatible changes](#backward-incompatible-changes-in-10) you'll
 want to be aware of when upgrading from StateMachine 0.9.0 or earlier. We've
 [begun the deprecation process for some features](#deprecated-features-in-10).
 

docs/releases/2.0.0.md

@@ -7,7 +7,7 @@ Welcome to StateMachine 2.0.0!
 This version is the first to take advantage of the Python3 improvements and is a huge internal refactoring removing the deprecated features on 1.*. We hope that you enjoy it.
 
 These release notes cover the [](#whats-new-in-20), as well as
-some [backwards incompatible changes](#backwards-incompatible-changes-in-20) you'll
+some [backward incompatible changes](#backward-incompatible-changes-in-20) you'll
 want to be aware of when upgrading from StateMachine 1.*.
 
 
@@ -18,9 +18,24 @@ StateMachine 2.0 supports Python 3.7, 3.8, 3.9, 3.10, and 3.11.
 
 ## What's new in 2.0
 
+### Run to completion (RTC) by default
+
+There are now two distinct methods for processing events in the library. The **new default** is to run in
+{ref}`RTC model` to be compliant with the specs, where the {ref}`event` is put on a queue before processing.
+You can also configure your state machine to run back in {ref}`Non-RTC model`, where the {ref}`event` will
+be run immediately and nested events will be chained.
+
+This means that the state machine now completes all the actions associated with an event before moving on to the next event.
+Even if you trigger an event inside an action.
+
+```{seealso}
+See {ref}`processing model` for more details.
+```
+
 ### State names are now optional
 
-{ref}`State` names are now by default derived from the class variable that they are assigned to. You can keep declaring explicit names, but we encourage you to only assign a name
+{ref}`State` names are now by default derived from the class variable that they are assigned to.
+You can keep declaring explicit names, but we encourage you to only assign a name
 when it is different than the one derived from its id.
 
 ```py
@@ -90,6 +105,13 @@ See {ref}`internal transition` for more details.
 
 ### Statemachine class changes in 2.0
 
+#### The new processing model (RTC) by default
+
+While we've figured out a way to keep near complete backwards compatible changes to the new
+{ref}`Run to completion (RTC) by default` feature (all built-in examples run without change),
+if you encounter problems when upgrading to this version, you can still switch back to the old
+{ref}`Non-RTC model`. Be aware that we may remove the {ref}`Non-RTC model` in the future.
+
 #### `StateMachine.run` removed in favor of `StateMachine.send`
 
 ```py

docs/transitions.md

@@ -219,7 +219,7 @@ an action that `echoes` back the parameters informed.
     :language: python
     :linenos:
     :emphasize-lines: 10
-    :lines: 12-15
+    :lines: 12-21
 ```
 
 

pyproject.toml

@@ -94,6 +94,9 @@ select = [
     "B",  # flake8-bugbear
     "PT", # flake8-pytest-style
 ]
+ignore = [
+    "UP006", # `use-pep585-annotation` Requires Python3.9+
+]
 
 line-length = 99
 
@@ -125,8 +128,7 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 target-version = "py311"
 
 [tool.ruff.mccabe]
-# Unlike Flake8, default to a complexity level of 10.
-max-complexity = 5
+max-complexity = 6
 
 [tool.ruff.isort]
 force-single-line = true

statemachine/dispatcher.py

@@ -37,7 +37,7 @@ def _get_func_by_attr(attr, *configs):
     return func, config.obj
 
 
-def ensure_callable(attr, *objects):  # noqa: C901
+def ensure_callable(attr, *objects):
     """Ensure that `attr` is a callable, if not, tries to retrieve one from any of the given
     `objects`.
 

statemachine/event.py

@@ -1,19 +1,21 @@
+from typing import TYPE_CHECKING
+
 from .event_data import EventData
 from .event_data import TriggerData
 from .exceptions import TransitionNotAllowed
 
+if TYPE_CHECKING:
+    from .statemachine import StateMachine
+
 
 class Event:
-    def __init__(self, name):
-        self.name = name
+    def __init__(self, name: str):
+        self.name: str = name
 
     def __repr__(self):
         return f"{type(self).__name__}({self.name!r})"
 
-    def __call__(self, machine, *args, **kwargs):
-        return self.trigger(machine, *args, **kwargs)
-
-    def trigger(self, machine, *args, **kwargs):
+    def trigger(self, machine: "StateMachine", *args, **kwargs):
         def trigger_wrapper():
             """Wrapper that captures event_data as closure."""
             trigger_data = TriggerData(
@@ -27,10 +29,6 @@ def trigger_wrapper():
         return machine._process(trigger_wrapper)
 
     def _trigger(self, trigger_data: TriggerData):
-        event_data = self._process(trigger_data)
-        return event_data.result
-
-    def _process(self, trigger_data: TriggerData):
         state = trigger_data.machine.current_state
         for transition in state.transitions:
             if not transition.match(trigger_data.event):
@@ -43,15 +41,15 @@ def _process(self, trigger_data: TriggerData):
         else:
             raise TransitionNotAllowed(trigger_data.event, state)
 
-        return event_data
+        return event_data.result
 
 
 def trigger_event_factory(event):
     """Build a method that sends specific `event` to the machine"""
     event_instance = Event(event)
 
     def trigger_event(self, *args, **kwargs):
-        return event_instance(self, *args, **kwargs)
+        return event_instance.trigger(self, *args, **kwargs)
 
     trigger_event.name = event
     trigger_event.identifier = event