python-statemachine 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

statemachine/engines/base.py

@@ -1,8 +1,11 @@
 import logging
 from collections.abc import Callable
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from dataclasses import dataclass
 from dataclasses import field
-from itertools import chain
+from heapq import heappop
 from queue import PriorityQueue
 from queue import Queue
 from threading import Lock
@@ -26,6 +29,24 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+_running_engine: "ContextVar[BaseEngine | None]" = ContextVar("_running_engine", default=None)
+"""The engine whose step the current thread or task is running, if any.
+
+A context variable is per thread and per asyncio task: asyncio copies it into the tasks a
+step creates, so callbacks see it, while another thread or an independent coroutine sending
+to the same machine does not.
+"""
+
+
+@contextmanager
+def _processing_step(engine: "BaseEngine") -> Iterator[None]:
+    """Mark the current context as running a step of ``engine``, until the block ends."""
+    token = _running_engine.set(engine)
+    try:
+        yield
+    finally:
+        _running_engine.reset(token)
+
 
 @dataclass(frozen=True, unsafe_hash=True, eq=True)
 class StateTransition:
@@ -33,6 +54,13 @@ class StateTransition:
     state: State
 
 
+#: What entering states needs, worked out before any callback runs: the states in entry order,
+#: those entered by default, the default history content, and the new configuration.
+_EntryPlan = tuple[
+    list[StateTransition], OrderedSet[StateTransition], dict[str, Any], OrderedSet[State]
+]
+
+
 class EventQueue:
     def __init__(self):
         self.queue: Queue = PriorityQueue()
@@ -41,7 +69,16 @@ class EventQueue:
         return f"EventQueue({self.queue.queue!r}, size={self.queue.qsize()})"
 
     def is_empty(self):
-        return self.queue.qsize() == 0
+        """Whether the queue holds no trigger that has not been cancelled."""
+        with self.queue.mutex:
+            self._drop_cancelled_head()
+            return not self.queue.queue
+
+    def _drop_cancelled_head(self):
+        """Drop the cancelled triggers at the head. The caller holds the queue's mutex."""
+        heap = self.queue.queue
+        while heap and heap[0].cancelled:
+            heappop(heap)
 
     def put(self, trigger_data: TriggerData):
         """Put the trigger on the queue without blocking the caller."""
@@ -51,10 +88,30 @@ class EventQueue:
         """Pop a trigger from the queue without blocking the caller."""
         return self.queue.get(block=False)
 
+    def pop_due(self, now: float) -> "TriggerData | None":
+        """Pop the trigger at the head if it is due by ``now``.
+
+        Returns ``None`` when the queue is empty or its head is not yet due. The head stays in
+        the queue until it is popped, so a :meth:`cancel` from another thread always finds it.
+        """
+        with self.queue.mutex:
+            self._drop_cancelled_head()
+            heap: list[TriggerData] = self.queue.queue
+            if not heap or heap[0].execution_time > now:
+                return None
+            return heappop(heap)
+
     def clear(self):
         with self.queue.mutex:
             self.queue.queue.clear()
 
+    def drain(self) -> list[TriggerData]:
+        """Remove every trigger from the queue and return those not cancelled."""
+        with self.queue.mutex:
+            triggers = [trigger for trigger in self.queue.queue if not trigger.cancelled]
+            self.queue.queue.clear()
+        return triggers
+
     def reject_futures(self, exc: Exception):
         """Reject all unresolved futures in the queue.
 
@@ -67,15 +124,17 @@ class EventQueue:
                 if future is not None and not future.done():
                     future.set_exception(exc)
 
-    def remove(self, send_id: str):
-        # We use the internal `queue` to make thins faster as the mutex
-        # is protecting the block below
+    def cancel(self, send_id: str):
+        """Cancel every trigger with this ``send_id``, and answer a caller awaiting one with
+        ``None``. Each stays where it is, so the heap keeps its order, until :meth:`is_empty`
+        drops it from the head."""
         with self.queue.mutex:
-            self.queue.queue = [
-                trigger_data
-                for trigger_data in self.queue.queue
-                if trigger_data.send_id != send_id
-            ]
+            for trigger_data in self.queue.queue:
+                if trigger_data.send_id == send_id:
+                    trigger_data.cancelled = True
+                    future = trigger_data.future
+                    if future is not None and not future.done():
+                        future.set_result(None)
 
 
 _ERROR_EXECUTION = "error.execution"
@@ -97,40 +156,55 @@ class BaseEngine:
         self._debug = logger.debug if logger.isEnabledFor(logging.DEBUG) else lambda *a, **k: None
         self._root_parallel_final_pending: "State | None" = None
 
-    def empty(self):  # pragma: no cover
-        return self.external_queue.is_empty()
-
     def clear_cache(self):
         """Clears the cache. Should be called at the start of each processing loop."""
         self._cache.clear()
 
-    def put(self, trigger_data: TriggerData, internal: bool = False, _delayed: bool = False):
-        """Put the trigger on the queue without blocking the caller."""
+    def put(self, trigger_data: TriggerData, internal: bool = False):
+        """Put the trigger on the queue without blocking the caller.
+
+        An ``internal`` trigger joins the internal queue only when this machine raises it while
+        running a step. Put from outside, including from a step of another machine, there is
+        no macrostep to join, so it goes to the external queue, where its caller gets its
+        result.
+        """
         if not self.running and not self.sm.allow_event_without_transition:
             raise TransitionNotAllowed(trigger_data.event, self.sm.configuration)
 
+        internal = internal and _running_engine.get() is self
         if internal:
             self.internal_queue.put(trigger_data)
         else:
             self.external_queue.put(trigger_data)
 
-        if not _delayed:
-            self._debug(
-                "%s New event '%s' put on the '%s' queue",
-                self._log_id,
-                trigger_data.event,
-                "internal" if internal else "external",
-            )
-
-    def pop(self):  # pragma: no cover
-        return self.external_queue.pop()
+        self._debug(
+            "%s New event '%s' put on the '%s' queue",
+            self._log_id,
+            trigger_data.event,
+            "internal" if internal else "external",
+        )
 
     def clear(self):
+        self.internal_queue.clear()
         self.external_queue.clear()
 
+    def _drop_external_events(self):
+        """Drop the external events left once the machine has stopped, answering a caller
+        awaiting one as the stopped machine answers a new event."""
+        for trigger_data in self.external_queue.drain():
+            future = trigger_data.future
+            if future is None or future.done():
+                continue
+            if self.sm.allow_event_without_transition:
+                future.set_result(None)
+            else:
+                future.set_exception(
+                    TransitionNotAllowed(trigger_data.event, self.sm.configuration)
+                )
+
     def cancel_event(self, send_id: str):
         """Cancel the event with the given send_id."""
-        self.external_queue.remove(send_id)
+        self.external_queue.cancel(send_id)
 
     def _on_error_handler(self) -> "Callable[[Exception], None] | None":
         """Return a per-block error handler, or ``None``.
@@ -324,114 +398,31 @@ class BaseEngine:
 
         return targets
 
-    def select_eventless_transitions(self, trigger_data: TriggerData):
-        """
-        Select the eventless transitions that match the trigger data.
-        """
-        return self._select_transitions(trigger_data, lambda t, _e: t.is_eventless)
-
-    def select_transitions(self, trigger_data: TriggerData) -> OrderedSet[Transition]:
-        """
-        Select the transitions that match the trigger data.
-        """
-        return self._select_transitions(trigger_data, lambda t, e: t.match(e))
-
-    def _first_transition_that_matches(
+    def _get_args_kwargs(
         self,
-        state: State,
+        transition: Transition,
         trigger_data: TriggerData,
-        predicate: Callable,
-    ) -> "Transition | None":
-        for s in chain([state], state.ancestors()):
-            transition: Transition
-            for transition in s.transitions:
-                if (
-                    not transition.initial
-                    and predicate(transition, trigger_data.event)
-                    and self._conditions_match(transition, trigger_data)
-                ):
-                    return transition
-        return None
-
-    def _select_transitions(
-        self, trigger_data: TriggerData, predicate: Callable
-    ) -> OrderedSet[Transition]:
-        """Select the transitions that match the trigger data."""
-        enabled_transitions = OrderedSet[Transition]()
-
-        # Get atomic states, TODO: sorted by document order
-        atomic_states = (state for state in self.sm.configuration if state.is_atomic)
-
-        for state in atomic_states:
-            transition = self._first_transition_that_matches(state, trigger_data, predicate)
-            if transition is not None:
-                enabled_transitions.add(transition)
-
-        return self._filter_conflicting_transitions(enabled_transitions)
-
-    def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
-        """Process a single set of transitions in a 'lock step'.
-        This includes exiting states, executing transition content, and entering states.
-        """
-        self._microstep_count += 1
-        self._debug(
-            "%s macro:%d micro:%d transitions: %s",
-            self._log_id,
-            self._macrostep_count,
-            self._microstep_count,
-            transitions,
-        )
-        previous_configuration = self.sm.configuration
-        try:
-            result = self._execute_transition_content(
-                transitions, trigger_data, lambda t: t.before.key
-            )
-
-            states_to_exit = self._exit_states(transitions, trigger_data)
-            result += self._enter_states(
-                transitions, trigger_data, states_to_exit, previous_configuration
-            )
-        except InvalidDefinition:
-            self.sm.configuration = previous_configuration
-            raise
-        except Exception as e:
-            self.sm.configuration = previous_configuration
-            self._handle_error(e, trigger_data)
-            return None
-
-        try:
-            self._execute_transition_content(
-                transitions,
-                trigger_data,
-                lambda t: t.after.key,
-                set_target_as_state=True,
-            )
-        except InvalidDefinition:
-            raise
-        except Exception as e:
-            self._handle_error(e, trigger_data)
-
-        if len(result) == 0:
-            result = None
-        elif len(result) == 1:
-            result = result[0]
-
-        return result
-
-    def _get_args_kwargs(
-        self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+        target: "State | None" = None,
+        source: "State | None" = None,
     ):
         # Generate a unique key for the cache, the cache is invalidated once per loop
-        cache_key = (id(transition), id(trigger_data), id(target))
+        cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
         # Check the cache for existing results
         if cache_key in self._cache:
             return self._cache[cache_key]
 
         event_data = EventData(trigger_data=trigger_data, transition=transition)
+        # Bind `state`/`target` to the individual state being entered, and
+        # `state`/`source` to the individual state being exited, so the generic
+        # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+        # compound state boundaries (the transition only knows its own endpoints).
         if target:
             event_data.state = target
             event_data.target = target
+        if source:
+            event_data.state = source
+            event_data.source = source
 
         args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -468,7 +459,7 @@ class BaseEngine:
             state = info.state
             for history in state.history:
                 if history.type.is_deep:
-                    history_value = [s for s in self.sm.configuration if s.is_descendant(state)]  # noqa: E501
+                    history_value = [s for s in self.sm.configuration if s.is_descendant(state)]
                 else:  # shallow history
                     history_value = [s for s in self.sm.configuration if s.parent == state]
 
@@ -488,29 +479,6 @@ class BaseEngine:
         if not self.sm.atomic_configuration_update:
             self.sm._config.discard(state)
 
-    def _exit_states(
-        self, enabled_transitions: list[Transition], trigger_data: TriggerData
-    ) -> OrderedSet[State]:
-        """Compute and process the states to exit for the given transitions."""
-        ordered_states, result = self._prepare_exit_states(enabled_transitions)
-        on_error = self._on_error_handler()
-
-        for info in ordered_states:
-            # Cancel invocations for this state before executing exit handlers.
-            if info.state is not None:  # pragma: no branch
-                self._invoke_manager.cancel_for_state(info.state)
-
-            args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
-
-            # Execute `onexit` handlers — same per-block error isolation as onentry.
-            if info.state is not None:  # pragma: no branch
-                self._debug("%s Exiting state: %s", self._log_id, info.state)
-                self.sm._callbacks.call(info.state.exit.key, *args, on_error=on_error, **kwargs)
-
-            self._remove_state_from_configuration(info.state)
-
-        return result
-
     def _execute_transition_content(
         self,
         enabled_transitions: list[Transition],
@@ -538,7 +506,7 @@ class BaseEngine:
         enabled_transitions: list[Transition],
         states_to_exit: OrderedSet[State],
         previous_configuration: OrderedSet[State],
-    ) -> "tuple[list[StateTransition], OrderedSet[StateTransition], dict[str, Any], OrderedSet[State]]":  # noqa: E501
+    ) -> _EntryPlan:
         """Compute entry set, ordering, and new configuration. Pure computation, no callbacks.
 
         Returns:
@@ -579,7 +547,7 @@ class BaseEngine:
         self.running = False
         try:
             self._invoke_manager.cancel_all()
-        except Exception:  # pragma: no cover
+        except Exception:
             self._debug("%s Error stopping engine", self._log_id, exc_info=True)
 
     def __del__(self):
@@ -622,7 +590,7 @@ class BaseEngine:
                     if grandparent.parent is None:
                         self._root_parallel_final_pending = grandparent
 
-    def _enter_states(  # noqa: C901
+    def _enter_states(
         self,
         enabled_transitions: list[Transition],
         trigger_data: TriggerData,
@@ -744,7 +712,7 @@ class BaseEngine:
                     default_history_content,
                 )
 
-    def add_descendant_states_to_enter(  # noqa: C901
+    def add_descendant_states_to_enter(
         self,
         info: StateTransition,
         states_to_enter,
@@ -764,121 +732,164 @@ class BaseEngine:
         state = info.state
 
         if state and state.is_history:
-            # Handle history state
-            state = cast(HistoryState, state)
-            parent_id = state.parent and state.parent.id
-            default_history_content[parent_id] = [info]
-            if state.id in self.sm.history_values:
-                self._debug(
-                    "%s History state '%s.%s' %s restoring: '%s'",
-                    self._log_id,
-                    state.parent,
-                    state,
-                    state.type.value,
-                    [s.id for s in self.sm.history_values[state.id]],
-                )
-                for history_state in self.sm.history_values[state.id]:
-                    info_to_add = StateTransition(transition=info.transition, state=history_state)
-                    if state.type.is_deep:
-                        states_to_enter.add(info_to_add)
-                    else:
-                        self.add_descendant_states_to_enter(
-                            info_to_add,
-                            states_to_enter,
-                            states_for_default_entry,
-                            default_history_content,
-                        )
-                for history_state in self.sm.history_values[state.id]:
-                    info_to_add = StateTransition(transition=info.transition, state=history_state)
-                    self.add_ancestor_states_to_enter(
-                        info_to_add,
-                        state.parent,
-                        states_to_enter,
-                        states_for_default_entry,
-                        default_history_content,
-                    )
-            else:
-                # Handle default history content
-                self._debug(
-                    "%s History state '%s.%s' default content: %s",
-                    self._log_id,
-                    state.parent,
-                    state,
-                    [t.target.id for t in state.transitions if t.target],
-                )
-
-                for transition in state.transitions:
-                    target = cast(State, transition.target)
-                    info_history = StateTransition(transition=transition, state=target)
-                    default_history_content[parent_id].append(info_history)
-                    self.add_descendant_states_to_enter(
-                        info_history,
-                        states_to_enter,
-                        states_for_default_entry,
-                        default_history_content,
-                    )  # noqa: E501
-                for transition in state.transitions:
-                    target = cast(State, transition.target)
-                    info_history = StateTransition(transition=transition, state=target)
-
-                    self.add_ancestor_states_to_enter(
-                        info_history,
-                        state.parent,
-                        states_to_enter,
-                        states_for_default_entry,
-                        default_history_content,
-                    )  # noqa: E501
+            self._add_history_states_to_enter(
+                info,
+                cast(HistoryState, state),
+                states_to_enter,
+                states_for_default_entry,
+                default_history_content,
+            )
             return
 
         # Add the state to the entry set
-        if (
-            self.sm.enable_self_transition_entries
-            or not info.transition.internal
-            or not (
-                info.transition.is_self
-                or (
-                    info.transition.target
-                    and info.transition.target.is_descendant(info.transition.source)
-                )
-            )
-        ):
+        if self._enters_target(info.transition):
             states_to_enter.add(info)
         state = info.state
 
         if state.parallel:
-            for child_state in state.states:
-                if not any(  # pragma: no branch
-                    s.state.is_descendant(child_state) for s in states_to_enter
-                ):
-                    info_to_add = StateTransition(transition=info.transition, state=child_state)
+            self._add_regions_to_enter(
+                info, states_to_enter, states_for_default_entry, default_history_content
+            )
+        elif state.is_compound:
+            self._add_initial_states_to_enter(
+                info, states_to_enter, states_for_default_entry, default_history_content
+            )
+
+    def _enters_target(self, transition: Transition) -> bool:
+        """Whether taking ``transition`` enters its target.
+
+        An internal transition to its own source, or to a descendant of it, does not, unless
+        the machine enables self-transition entries.
+        """
+        return (
+            self.sm.enable_self_transition_entries
+            or not transition.internal
+            or not (
+                transition.is_self
+                or (transition.target and transition.target.is_descendant(transition.source))
+            )
+        )
+
+    def _add_history_states_to_enter(
+        self,
+        info: StateTransition,
+        state: HistoryState,
+        states_to_enter,
+        states_for_default_entry,
+        default_history_content,
+    ):
+        """Add the states a history state stands for: those it recorded, or its default."""
+        parent_id = state.parent and state.parent.id
+        default_history_content[parent_id] = [info]
+        if state.id in self.sm.history_values:
+            self._debug(
+                "%s History state '%s.%s' %s restoring: '%s'",
+                self._log_id,
+                state.parent,
+                state,
+                state.type.value,
+                [s.id for s in self.sm.history_values[state.id]],
+            )
+            for history_state in self.sm.history_values[state.id]:
+                info_to_add = StateTransition(transition=info.transition, state=history_state)
+                if state.type.is_deep:
+                    states_to_enter.add(info_to_add)
+                else:
                     self.add_descendant_states_to_enter(
                         info_to_add,
                         states_to_enter,
                         states_for_default_entry,
                         default_history_content,
                     )
-        elif state.is_compound:
-            states_for_default_entry.add(info)
-            transition = next(t for t in state.transitions if t.initial)
-            # Process all targets (supports multi-target initial transitions for parallel regions)
-            for initial_target in transition.targets:
-                info_initial = StateTransition(transition=transition, state=initial_target)
+            for history_state in self.sm.history_values[state.id]:
+                info_to_add = StateTransition(transition=info.transition, state=history_state)
+                self.add_ancestor_states_to_enter(
+                    info_to_add,
+                    state.parent,
+                    states_to_enter,
+                    states_for_default_entry,
+                    default_history_content,
+                )
+        else:
+            # Handle default history content
+            self._debug(
+                "%s History state '%s.%s' default content: %s",
+                self._log_id,
+                state.parent,
+                state,
+                [t.target.id for t in state.transitions if t.target],
+            )
+
+            for transition in state.transitions:
+                target = cast(State, transition.target)
+                info_history = StateTransition(transition=transition, state=target)
+                default_history_content[parent_id].append(info_history)
                 self.add_descendant_states_to_enter(
-                    info_initial,
+                    info_history,
                     states_to_enter,
                     states_for_default_entry,
                     default_history_content,
                 )
-            for initial_target in transition.targets:
-                info_initial = StateTransition(transition=transition, state=initial_target)
+            for transition in state.transitions:
+                target = cast(State, transition.target)
+                info_history = StateTransition(transition=transition, state=target)
+
                 self.add_ancestor_states_to_enter(
-                    info_initial,
-                    state,
+                    info_history,
+                    state.parent,
                     states_to_enter,
                     states_for_default_entry,
                     default_history_content,
                 )
 
+    def _add_regions_to_enter(
+        self,
+        info: StateTransition,
+        states_to_enter,
+        states_for_default_entry,
+        default_history_content,
+    ):
+        """Add each region of a parallel state, unless a state inside it is already entered."""
+        for child_state in info.state.states:
+            if not any(s.state.is_descendant(child_state) for s in states_to_enter):
+                info_to_add = StateTransition(transition=info.transition, state=child_state)
+                self.add_descendant_states_to_enter(
+                    info_to_add,
+                    states_to_enter,
+                    states_for_default_entry,
+                    default_history_content,
+                )
+
+    def _add_initial_states_to_enter(
+        self,
+        info: StateTransition,
+        states_to_enter,
+        states_for_default_entry,
+        default_history_content,
+    ):
+        """Add the states a compound state's initial transition targets."""
+        state = info.state
+        states_for_default_entry.add(info)
+        transition = next(t for t in state.transitions if t.initial)
+        # Process all targets (supports multi-target initial transitions for parallel regions)
+        for initial_target in transition.targets:
+            info_initial = StateTransition(transition=transition, state=initial_target)
+            self.add_descendant_states_to_enter(
+                info_initial,
+                states_to_enter,
+                states_for_default_entry,
+                default_history_content,
+            )
+        for initial_target in transition.targets:
+            info_initial = StateTransition(transition=transition, state=initial_target)
+            self.add_ancestor_states_to_enter(
+                info_initial,
+                state,
+                states_to_enter,
+                states_for_default_entry,
+                default_history_content,
+            )
+
     def add_ancestor_states_to_enter(
         self,
         info: StateTransition,
@@ -941,9 +952,10 @@ class BaseEngine:
             self.running = False
 
     def is_in_final_state(self, state: State) -> bool:
-        if state.is_compound:
-            return any(s.final and s in self.sm.configuration for s in state.states)
-        elif state.parallel:  # pragma: no cover — requires nested parallel-in-parallel
+        """Whether every region of a parallel state, or a compound state, rests in a final child.
+
+        An atomic state has no children, so it never does.
+        """
+        if state.parallel:
             return all(self.is_in_final_state(s) for s in state.states)
-        else:  # pragma: no cover — atomic states are never "in final state"
-            return False
+        return any(s.final and s in self.sm.configuration for s in state.states)