chartflow 0.1__py3-none-any.whl

chartflow/fsm/scheduler.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+"""
+qfsm Scheduler Module
+
+A singleton scheduler class that manages Logic instances in priority queues,
+handling the 4-phase lifecycle: _check, _enter, _step, _exit.
+"""
+
+from PyQt6.QtWidgets import QApplication
+
+
+
+import bisect
+import sys
+import traceback
+from typing import Any, Self
+
+from chartflow.fsm.utils import GetES
+
+# Qt integration for processEvents during long operations
+_qt_app = None
+def _process_qt_events():
+    """Process Qt events if available, to keep UI responsive during long operations."""
+    global _qt_app
+    if _qt_app is None:
+        try:
+            _qt_app = QApplication.instance()
+        except ImportError:
+            pass
+    if _qt_app:
+        _qt_app.processEvents()
+
+
+# Forward reference for Logic type - avoids circular imports
+# Logic class is expected to have: NAME, PRIORITY, alive, enabled, _isEntered
+# and methods: _check(), _enter(), _step(), _exit()
+
+
+class Scheduler:
+    """
+    Singleton scheduler for managing Logic instances.
+    
+    The Scheduler maintains priority-sorted queues of Logic instances and
+    orchestrates their lifecycle through four phases:
+    1. Check - validate instance state via _check()
+    2. Enter - initialize instances via _enter()  
+    3. Step - execute logic via _step()
+    4. Exit - cleanup dead instances via _exit()
+    
+    Higher PRIORITY values are processed first.
+    
+    Example:
+        >>> scheduler = Scheduler()
+        >>> scheduler.login(MyLogicClass)
+        >>> instance = scheduler.add("MyLogic", some_instance)
+        >>> scheduler.handle()  # Process one tick
+    """
+
+    _instance: Scheduler | None = None
+    _global_enabled: bool = True
+
+    def __new__(cls) -> Self:
+        """Singleton pattern - ensures only one Scheduler instance exists."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize the Scheduler with empty queues."""
+        if self._initialized:
+            return
+
+        # Registered class prototypes: {name: class}
+        self.prototypes: dict[str, type] = {}
+
+        # Active Logic instances, sorted by PRIORITY (descending)
+        self.updates: list[Any] = []
+
+        # Logic instances waiting to be added to updates
+        self.waits: list[Any] = []
+
+        # Instance-level enable flag
+        self._enabled: bool = True
+
+        # Tick counter - increments each handle() call
+        self._tick: int = 0
+
+        # Event system
+        self._eda = GetES()
+
+        # Listen for system_next event to trigger handle()
+        self._eda.listenFor("system_next", self._onNextTick)
+
+        self._initialized = True
+
+    def login(self, prototype: type) -> None:
+        """
+        Register a Logic class prototype with the Scheduler.
+        
+        Validates that the class has a valid NAME attribute.
+        Called automatically by StageMachineLogicMeta during class creation.
+        
+        Args:
+            prototype: A Logic subclass to register
+            
+        Raises:
+            ValueError: If NAME is empty or not defined
+            
+        Example:
+            >>> class MyLogic(Logic):
+            ...     NAME = "MyLogic"
+            >>> Scheduler().login(MyLogic)
+        """
+        name: str = getattr(prototype, 'NAME', '')
+        
+        if not name:
+            raise ValueError(
+                f"Cannot register {prototype.__name__}: "
+                f"NAME attribute is empty or not defined"
+            )
+        
+        if name[-1].isdigit():
+            raise ValueError(
+                f"Cannot register {prototype.__name__}: "
+                f"NAME '{name}' must not end with a digit"
+            )
+        
+        if name in self.prototypes:
+            # Allow re-registration for hot-reloading scenarios
+            pass
+            
+        self.prototypes[name] = prototype
+
+    def add(self, obj_or_name: Any, *args: Any) -> Any | None:
+        """
+        Add a Logic instance to the scheduling queue.
+        
+        Can accept either:
+        - A Logic instance directly
+        - A string name of a registered prototype to instantiate
+        
+        Args:
+            obj_or_name: Either a Logic instance or registered class name
+            *args: Arguments to pass when instantiating from name
+            
+        Returns:
+            The added Logic instance, or None if creation failed
+            
+        Example:
+            >>> # Add by instance
+            >>> scheduler.add(MyLogic())
+            >>> # Add by name with arguments  
+            >>> scheduler.add("MyLogic", some_instance)
+        """
+        instance: Any | None = None
+        
+        match obj_or_name:
+            case str(name):
+                # Create from prototype name
+                if name not in self.prototypes:
+                    raise KeyError(
+                        f"Unknown Logic prototype: '{name}'. "
+                        f"Registered: {list(self.prototypes.keys())}"
+                    )
+                prototype = self.prototypes[name]
+                instance = prototype(*args)
+                
+            case obj if hasattr(obj, '_check') and hasattr(obj, '_step'):
+                # Add existing instance (duck typing for Logic-like objects)
+                instance = obj
+                
+            case _:
+                raise TypeError(
+                    f"Expected Logic-like instance or str name, got {type(obj_or_name).__name__}"
+                )
+        
+        if instance is not None:
+            # Check for duplicate ID in waits or updates
+            instance_id = id(instance)
+            for existing in self.waits:
+                if id(existing) == instance_id:
+                    return instance  # Already in waits, skip
+            for existing in self.updates:
+                if id(existing) == instance_id:
+                    return instance  # Already in updates, skip
+            self.waits.append(instance)
+
+        return instance
+
+    def handle(self) -> None:
+        """
+        Main processing loop - executes one tick of the scheduler.
+        
+        Performs four phases in order:
+        1. **Promote**: Move instances from waits to updates (sorted by PRIORITY)
+        2. **Check**: Call _check() on all instances in updates
+        3. **Enter**: Call _enter() on instances that haven't entered yet
+        4. **Step**: Call _step() on all entered instances  
+        5. **Exit**: Remove dead instances (alive=False) and call _exit()
+        
+        The scheduler respects both global and instance-level enable flags.
+        Disabled instances are skipped during processing.
+        
+        Example:
+            >>> scheduler = Scheduler()
+            >>> while running:
+            ...     scheduler.handle()
+        """
+        if not (self._enabled and Scheduler._global_enabled):
+            return
+
+        # Increment tick counter
+        self._tick += 1
+
+        # Phase 1: Promote waiting instances to updates queue
+        self._promote_waits()
+        
+        if not self.updates:
+            return
+        
+        # Phase 2: Check - validate all instances
+        self._phase_check()
+        
+        # Phase 3: Enter - initialize new instances
+        self._phase_enter()
+        
+        # Phase 4: Step - execute logic
+        self._phase_step()
+        
+        # Phase 5: Exit - cleanup dead instances
+        self._phase_exit()
+
+    def _promote_waits(self) -> None:
+        """Move instances from waits to updates, maintaining priority order."""
+        for instance in self.waits:
+            self._insert_by_priority(instance)
+        self.waits.clear()
+
+    def _onNextTick(self, _data: Any) -> None:
+        """Handle system_next event by calling handle()."""
+        self.handle()
+
+    def Cleanup(self) -> None:
+        """Cleanup resources - cancel event listener."""
+        if hasattr(self, '_eda') and self._eda:
+            self._eda.cancelListen("system_next", self._onNextTick)
+
+    def __del__(self) -> None:
+        """Destructor - ensure cleanup is called."""
+        self.Cleanup()
+
+    def _insert_by_priority(self, instance: Any) -> None:
+        """
+        Insert instance into updates using binary search for efficiency.
+        
+        Higher PRIORITY values are placed first (descending order).
+        Uses bisect for O(log n) insertion.
+        """
+        priority = getattr(instance, 'PRIORITY', 0)
+        
+        # Find insertion point for descending order
+        # We negate priority since bisect assumes ascending order
+        insertion_point = bisect.bisect_left(
+            [-getattr(obj, 'PRIORITY', 0) for obj in self.updates],
+            -priority
+        )
+        self.updates.insert(insertion_point, instance)
+
+    def _phase_check(self) -> None:
+        """Phase 2: Call _check() on all instances."""
+        for instance in self.updates:
+            if instance.alive:
+                try:
+                    instance._check(False)
+                except Exception:
+                    # Errors in _check don't stop other instances, but print traceback
+                    exc_type, exc_value, exc_tb = sys.exc_info()
+                    tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+                    print(f"[{instance.name}] Error in _check:\n{tb_str}")
+
+    def _phase_enter(self) -> None:
+        """Phase 3: Call _enter() on instances not yet entered."""
+        for instance in self.updates:
+            if not instance.enabled or not instance.alive:
+                continue
+
+            # Check if already entered via _isEntered attribute
+            if not getattr(instance, '_isEntered', False):
+                try:
+                    instance._enter()
+                    instance._isEntered = True
+                except Exception:
+                    # Mark as entered even on error to prevent retry loops, but print traceback
+                    exc_type, exc_value, exc_tb = sys.exc_info()
+                    tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+                    print(f"[{instance.name}] Error in _enter:\n{tb_str}")
+                    instance._isEntered = True
+
+    def _phase_step(self) -> None:
+        """Phase 4: Call _step() on all entered, enabled instances."""
+        for instance in self.updates:
+            # Process Qt events before each instance to handle pending UI updates
+            _process_qt_events()
+
+            if not instance.enabled or not instance.alive:
+                continue
+
+            if getattr(instance, '_isEntered', False):
+                try:
+                    instance._step()
+                except Exception:
+                    # Errors in _step don't stop other instances, but print traceback
+                    exc_type, exc_value, exc_tb = sys.exc_info()
+                    tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+                    print(f"[{instance.name}] Error in _step:\n{tb_str}")
+
+    def _phase_exit(self) -> None:
+        """Phase 5: Remove dead instances and call _exit()."""
+        # Find indices of dead instances (alive=False)
+        dead_indices: list[int] = [
+            i for i, inst in enumerate(self.updates)
+            if not inst.alive
+        ]
+
+        # Process in reverse order to maintain valid indices
+        for idx in reversed(dead_indices):
+            instance = self.updates.pop(idx)
+            try:
+                instance._exit()
+            except Exception:
+                # Errors in _exit don't stop cleanup, but print traceback
+                exc_type, exc_value, exc_tb = sys.exc_info()
+                tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+                print(f"[{instance.name}] Error in _exit:\n{tb_str}")
+
+    def enable(self) -> None:
+        """Enable scheduling at the instance level."""
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable scheduling at the instance level."""
+        self._enabled = False
+
+    @staticmethod
+    def Enable() -> None:
+        """Enable scheduling globally (static method)."""
+        Scheduler._global_enabled = True
+
+    @staticmethod
+    def Disable() -> None:
+        """Disable scheduling globally (static method)."""
+        Scheduler._global_enabled = False
+
+    @property
+    def enabled(self) -> bool:
+        """Check if scheduler is enabled (both instance and global level)."""
+        return self._enabled and Scheduler._global_enabled
+
+    @property
+    def tick(self) -> int:
+        """Current tick counter (read-only)."""
+        return self._tick
+
+    def __len__(self) -> int:
+        """Return total number of managed instances."""
+        return len(self.updates) + len(self.waits)
+
+    def __contains__(self, instance: Any) -> bool:
+        """Check if an instance is managed by this scheduler."""
+        return instance in self.updates or instance in self.waits
+
+    def __repr__(self) -> str:
+        """String representation showing queue sizes."""
+        return (
+            f"{self.__class__.__name__}("
+            f"prototypes={len(self.prototypes)}, "
+            f"updates={len(self.updates)}, "
+            f"waits={len(self.waits)})"
+        )
+
+
+    def listenFor(self, event: str, callback: Any, *sources: str) -> Self:
+        """
+        Register an event listener.
+
+        Args:
+            event: Event name to listen for
+            callback: Function to call when event occurs
+            *sources: Optional source filters
+
+        Returns:
+            self for method chaining
+        """
+        self._eda.listenFor(event, callback, *sources)
+        return self
+
+    def cancelListen(self, event: str, callback: Any | None = None) -> bool:
+        """
+        Cancel an event listener.
+
+        Args:
+            event: Event name to stop listening for
+            callback: Specific callback to remove (None = all)
+
+        Returns:
+            True if listener was removed
+        """
+        return self._eda.cancelListen(event, callback)
+
+    def pushEvent(self, event: str, data: Any = None, *targets: str) -> int:
+        """
+        Push an event to listeners.
+
+        Args:
+            event: Event name to push
+            data: Event data
+            *targets: Optional target filters
+
+        Returns:
+            Number of listeners that received the event
+        """
+        return self._eda.pushEvent(event, data, *targets, source="system")
+
+
+
+__all__ = ['Scheduler']