mycorrhizal 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

mycorrhizal/hypha/core/runtime.py

@@ -8,63 +8,24 @@ Manages token flow, transition firing, and asyncio task coordination.
 
 import asyncio
 from asyncio import Event, Task
-from typing import Any, List, Dict, Optional, Set, Tuple, Callable, Deque, Union
-from collections import deque
-from itertools import product
+from typing import Any, List, Dict, Optional, Set, Tuple, Callable, Deque, Union, Type, get_type_hints
+from collections import deque, OrderedDict
+from itertools import product, combinations
 import inspect
 import logging
 
+from mycorrhizal.common.wrappers import create_view_from_protocol
+from mycorrhizal.common.compilation import (
+    _get_compiled_metadata,
+    _clear_compilation_cache,
+    CompiledMetadata,
+)
+from mycorrhizal.common.cache import InterfaceViewCache
 from .specs import NetSpec, PlaceSpec, TransitionSpec, ArcSpec, PlaceType, GuardSpec
 
 logger = logging.getLogger(__name__)
 
 
-# ======================================================================================
-# Interface Integration Helper
-# ======================================================================================
-
-
-def _create_interface_view_if_needed(bb: Any, handler: Callable) -> Any:
-    """
-    Create a constrained view if the handler has an interface type hint on its
-    blackboard parameter (second parameter, typically named 'bb').
-
-    This enables type-safe, constrained access to blackboard state based on
-    interface definitions created with @blackboard_interface.
-
-    Args:
-        bb: The blackboard instance
-        handler: The transition or IO handler function to check for interface type hints
-
-    Returns:
-        Either the original blackboard or a constrained view based on interface metadata
-    """
-    from typing import get_type_hints
-
-    try:
-        sig = inspect.signature(handler)
-        params = list(sig.parameters.values())
-
-        # Check second parameter (usually 'bb' at index 1)
-        # Transition handlers have signature: handler(consumed, bb, timebase, state?)
-        # IO input handlers have signature: handler(bb, timebase)
-        if len(params) >= 2:
-            # For transitions, bb is at index 1
-            # For IO input with 2 params, bb is at index 0
-            bb_param_index = 1 if len(params) >= 3 else 0
-
-            if params[bb_param_index].name == 'bb':
-                bb_type = get_type_hints(handler).get('bb')
-
-                # If type hint exists and has interface metadata
-                if bb_type and hasattr(bb_type, '_readonly_fields'):
-                    from mycorrhizal.common.wrappers import create_view_from_protocol
-                    return create_view_from_protocol(bb, bb_type)
-    except Exception:
-        # If anything goes wrong with type inspection, fall back to original bb
-        pass
-
-    return bb
 try:
     # Library should not configure root logging; be quiet by default
     logger.addHandler(logging.NullHandler())
@@ -76,12 +37,13 @@ except Exception:
 
 class PlaceRuntime:
     """Runtime execution of a place"""
-    
-    def __init__(self, spec: PlaceSpec, bb: Any, timebase: Any, fqn: str):
+
+    def __init__(self, spec: PlaceSpec, bb: Any, timebase: Any, fqn: str, net: Optional['NetRuntime'] = None):
         self.spec = spec
         self.fqn = fqn
         self.bb = bb
         self.timebase = timebase
+        self.net = net  # Reference to NetRuntime for cache access
         self.state = spec.state_factory() if spec.state_factory else None
         
         # tokens can be a bag (list) or queue (deque)
@@ -106,17 +68,36 @@ class PlaceRuntime:
         self.token_added_event.set()
     
     def remove_tokens(self, tokens_to_remove: List[Any]):
-        """Remove specific tokens from this place"""
+        """Remove specific tokens from this place.
+
+        Note: This operation is idempotent - if a token has already been removed
+        (e.g., by a competing transition), it will be safely skipped.
+        """
         if self.spec.place_type == PlaceType.BAG:
             for token in tokens_to_remove:
-                self.tokens.remove(token)
+                try:
+                    self.tokens.remove(token)
+                except ValueError:
+                    # Token already removed by another transition (race condition)
+                    # This is expected when multiple transitions compete
+                    pass
         else:  # QUEUE
-            temp = deque()
-            for token in self.tokens:
-                if token not in tokens_to_remove:
-                    temp.append(token)
-            self.tokens = temp
-        
+            # Try to use set for O(1) lookup if tokens are hashable
+            try:
+                removed_set = set(tokens_to_remove)
+                temp = deque()
+                for token in self.tokens:
+                    if token not in removed_set:
+                        temp.append(token)
+                self.tokens = temp
+            except TypeError:
+                # Fall back to O(n) lookup for unhashable tokens (e.g., Task objects)
+                temp = deque()
+                for token in self.tokens:
+                    if token not in tokens_to_remove:
+                        temp.append(token)
+                self.tokens = temp
+
         self.token_removed_event.set()
         self.token_removed_event.clear()
     
@@ -133,15 +114,22 @@ class PlaceRuntime:
             return
 
         # Create interface view if handler has interface type hint
-        bb_to_pass = _create_interface_view_if_needed(self.bb, self.spec.handler)
+        if self.net:
+            bb_to_pass = self.net._create_interface_view_if_needed(self.bb, self.spec.handler)
+        else:
+            bb_to_pass = self.bb
 
         async def io_input_loop():
             try:
-                sig = inspect.signature(self.spec.handler)
+                handler = self.spec.handler
+                if handler is None:
+                    return
+
+                sig = inspect.signature(handler)
                 if len(sig.parameters) == 2:
-                    gen = self.spec.handler(bb_to_pass, self.timebase)
+                    gen = handler(bb_to_pass, self.timebase)
                 else:
-                    gen = self.spec.handler()
+                    gen = handler()  # type: ignore[call-arg]
 
                 async for token in gen:
                     self.add_token(token)
@@ -156,7 +144,10 @@ class PlaceRuntime:
             return
 
         # Create interface view if handler has interface type hint
-        bb_to_pass = _create_interface_view_if_needed(self.bb, self.spec.handler)
+        if self.net:
+            bb_to_pass = self.net._create_interface_view_if_needed(self.bb, self.spec.handler)
+        else:
+            bb_to_pass = self.bb
 
         sig = inspect.signature(self.spec.handler)
         if len(sig.parameters) == 3:
@@ -188,6 +179,7 @@ class TransitionRuntime:
 
         self.task: Optional[Task] = None
         self._stop_event = Event()
+        self._spurious_wakeup_count = 0
     
     def add_input_arc(self, place_parts: Tuple[str, ...], arc: ArcSpec):
         """Register an input arc"""
@@ -197,40 +189,51 @@ class TransitionRuntime:
         """Register an output arc"""
         self.output_arcs.append(arc)
     
-    def _generate_token_combinations(self) -> List[Tuple[Tuple[Any, ...], ...]]:
+    def _generate_token_combinations(self):
         """
         Generate all valid token combinations for input arcs.
-        Returns list of tuples, where each tuple contains sub-tuples for each arc.
+        Returns generator of tuples, where each tuple contains sub-tuples for each arc.
+        Using generator instead of list for lazy evaluation - stops after guard selects first valid combination.
         """
         arc_tokens = []
-        
+
         for place_parts, arc in self.input_arcs:
             place = self.net.places[place_parts]
             tokens = place.peek_tokens(arc.weight)
-            
+
             if len(tokens) < arc.weight:
-                return []
-            
+                return iter([])  # Empty generator if insufficient tokens
+
             if arc.weight == 1:
                 arc_tokens.append([(t,) for t in tokens])
             else:
-                from itertools import combinations
                 arc_tokens.append(list(combinations(tokens, arc.weight)))
-        
+
         if not arc_tokens:
-            return []
-        
-        all_combinations = list(product(*arc_tokens))
-        return all_combinations
-    
-    async def _check_guard(self, combinations: List[Tuple[Tuple[Any, ...], ...]]) -> Optional[Tuple[Tuple[Any, ...], ...]]:
+            return iter([])  # Empty generator
+
+        # Return generator instead of list - lazy evaluation
+        return product(*arc_tokens)
+
+    async def _check_guard(self, combinations_generator) -> Optional[Tuple[Tuple[Any, ...], ...]]:
         """Check guard and return combination to consume, or None"""
+        # If no guard, return first combination from generator
         if not self.spec.guard:
-            return combinations[0] if combinations else None
-        
+            try:
+                return next(iter(combinations_generator))
+            except StopIteration:
+                return None
+
+        # Guard exists - need to build list for guard evaluation
+        # Guards expect to see all combinations to choose from
+        combinations_list = list(combinations_generator)
+
+        if not combinations_list:
+            return None
+
         guard_func = self.spec.guard.func
-        guard_result = guard_func(combinations, self.net.bb, self.net.timebase)
-        
+        guard_result = guard_func(combinations_list, self.net.bb, self.net.timebase)
+
         if inspect.isgenerator(guard_result):
             for result in guard_result:
                 if result is not None:
@@ -239,14 +242,14 @@ class TransitionRuntime:
             async for result in guard_result:
                 if result is not None:
                     return result
-        
+
         return None
     
     async def _fire_transition(self, consumed_combination: Tuple[Tuple[Any, ...], ...]):
         """Execute the transition with consumed tokens"""
         consumed_flat = []
         tokens_to_remove = {}
-        
+
         for i, (place_parts, arc) in enumerate(self.input_arcs):
             arc_tokens = consumed_combination[i]
             consumed_flat.extend(arc_tokens)
@@ -254,12 +257,13 @@ class TransitionRuntime:
             if place_parts not in tokens_to_remove:
                 tokens_to_remove[place_parts] = []
             tokens_to_remove[place_parts].extend(arc_tokens)
-        
+
+        # Remove tokens from input places
         for place_parts, tokens in tokens_to_remove.items():
             self.net.places[place_parts].remove_tokens(tokens)
 
         # Create interface view if handler has interface type hint
-        bb_to_pass = _create_interface_view_if_needed(self.net.bb, self.spec.handler)
+        bb_to_pass = self.net._create_interface_view_if_needed(self.net.bb, self.spec.handler)
 
         sig = inspect.signature(self.spec.handler)
         param_count = len(sig.parameters)
@@ -280,7 +284,7 @@ class TransitionRuntime:
             result = await results
             if result is not None:
                 await self._process_yield(result)
-    
+
     def _resolve_place_ref(self, place_ref) -> Optional[Tuple[str, ...]]:
         """Resolve a PlaceRef to runtime place parts.
 
@@ -427,42 +431,94 @@ class TransitionRuntime:
         """Main transition execution loop"""
         try:
             while not self._stop_event.is_set():
+                # Generator transitions (no inputs) fire continuously
+                if not self.input_arcs:
+                    # No input places - this is a generator transition
+                    # Fire continuously with empty consumed list
+                    logger.debug("[trans] %s is a generator, firing continuously", self.fqn)
+                    try:
+                        await self._fire_transition([])
+                    except Exception as e:
+                        logger.exception("[%s] Generator transition error", self.fqn)
+
+                    # Small delay to prevent busy-waiting
+                    await asyncio.sleep(0.01)
+                    continue
+
                 wait_tasks = []
                 for place_fqn, arc in self.input_arcs:
                     place = self.net.places[place_fqn]
                     wait_tasks.append(asyncio.create_task(place.token_added_event.wait()))
-                
+
                 if not wait_tasks:
                     break
-                
+
                 stop_task = asyncio.create_task(self._stop_event.wait())
                 wait_tasks.append(stop_task)
-                
+
                 done, pending = await asyncio.wait(
                     wait_tasks,
                     return_when=asyncio.FIRST_COMPLETED
                 )
-                
+
                 for task in pending:
                     task.cancel()
-                
+
                 if self._stop_event.is_set():
                     break
                 # Debug: indicate transition woke
                 logger.debug("[trans] %s woke; checking inputs", self.fqn)
 
-                for place_fqn, arc in self.input_arcs:
-                    place = self.net.places[place_fqn]
-                    place.token_added_event.clear()
-                
                 combinations = self._generate_token_combinations()
-                logger.debug("[trans] %s combinations=%d", self.fqn, len(combinations))
-                
-                if combinations:
+
+                # Check if there are any combinations (for generator, peek at first element)
+                combinations_iter = iter(combinations)
+                try:
+                    first_combo = next(combinations_iter)
+                    has_combinations = True
+                    # Put it back by creating a new generator with first element
+                    # We need to materialize the first element and chain it with the rest
+                    def chain_with_first(first, rest_iter):
+                        yield first
+                        yield from rest_iter
+                    combinations = chain_with_first(first_combo, combinations_iter)
+                except StopIteration:
+                    has_combinations = False
+
+                logger.debug("[trans] %s has_combinations=%s", self.fqn, has_combinations)
+
+                if has_combinations:
                     to_consume = await self._check_guard(combinations)
                     if to_consume:
                         await self._fire_transition(to_consume)
-        
+
+                        # Check if there are still tokens to process after firing
+                        remaining_combinations = self._generate_token_combinations()
+                        remaining_iter = iter(remaining_combinations)
+                        try:
+                            next(remaining_iter)
+                            has_remaining = True
+                        except StopIteration:
+                            has_remaining = False
+
+                        if not has_remaining:
+                            # No more tokens, clear the event and wait for new tokens
+                            for place_fqn, arc in self.input_arcs:
+                                place = self.net.places[place_fqn]
+                                place.token_added_event.clear()
+                            # else: there are still tokens, loop again immediately
+                else:
+                    # No combinations available (event was set spuriously or tokens consumed by another transition)
+                    # Spurious wakeup - clear events and go back to waiting
+                    self._spurious_wakeup_count += 1
+                    logger.debug(
+                        "[trans] %s spurious wakeup #%d, clearing events",
+                        self.fqn, self._spurious_wakeup_count
+                    )
+                    for place_fqn, arc in self.input_arcs:
+                        place = self.net.places[place_fqn]
+                        place.token_added_event.clear()
+
         except asyncio.CancelledError:
             pass
         except Exception:
@@ -478,10 +534,20 @@ class TransitionRuntime:
             except asyncio.CancelledError:
                 pass
 
+    def get_spurious_wakeup_count(self) -> int:
+        """Get the number of spurious wakeups for this transition.
+
+        Useful for monitoring and debugging race conditions.
+
+        Returns:
+            Number of spurious wakeups since transition started
+        """
+        return self._spurious_wakeup_count
+
 
 class NetRuntime:
     """Runtime execution of a complete Petri net"""
-    
+
     def __init__(self, spec: NetSpec, bb: Any, timebase: Any):
         self.spec = spec
         self.bb = bb
@@ -490,6 +556,8 @@ class NetRuntime:
         # Keep as Any to simplify gradual migration (place/transition runtime objects)
         self.places: Dict[Tuple[str, ...], Any] = {}
         self.transitions: Dict[Tuple[str, ...], Any] = {}
+        # Instance-local cache for interface views (no global state)
+        self._interface_cache = InterfaceViewCache(maxsize=256)
 
         self._flatten_spec(spec)
         self._build_runtime()
@@ -515,7 +583,7 @@ class NetRuntime:
         # Build all place runtimes
         for place_parts in list(self.places.keys()):
             place_spec = self._find_place_spec_by_parts(place_parts)
-            self.places[place_parts] = PlaceRuntime(place_spec, self.bb, self.timebase, '.'.join(place_parts))
+            self.places[place_parts] = PlaceRuntime(place_spec, self.bb, self.timebase, '.'.join(place_parts), self)
         
         # Build all transition runtimes  
         for trans_parts in list(self.transitions.keys()):
@@ -546,16 +614,77 @@ class NetRuntime:
             except Exception:
                 in_count = out_count = 0
             logger.debug("[runtime] %s inputs=%d outputs=%d", tfqn, in_count, out_count)
+
+    def _create_interface_view_if_needed(self, bb: Any, handler: Callable) -> Any:
+        """
+        Create a constrained view if the handler has an interface type hint on its
+        blackboard parameter.
+
+        This enables type-safe, constrained access to blackboard state based on
+        interface definitions created with @blackboard_interface.
+
+        The function signature can use an interface type:
+            async def my_transition(consumed, bb: MyInterface, timebase):
+                # bb is automatically a constrained view
+                yield {output: token}
+
+        Args:
+            bb: The blackboard instance
+            handler: The transition or IO handler function to check for interface type hints
+
+        Returns:
+            Either the original blackboard or a constrained view based on interface metadata
+
+        Raises:
+            TypeError: If handler is not callable or type hints are malformed
+            AttributeError: If type hints reference undefined types
+        """
+        # Get compiled metadata (uses EAFP pattern internally)
+        # Raises specific exceptions if compilation fails
+        metadata = _get_compiled_metadata(handler)
+
+        # If handler has interface type hint, create constrained view
+        if metadata.has_interface and metadata.interface_type:
+            # Use instance cache for this runtime
+            readonly_fields = metadata.readonly_fields if metadata.readonly_fields else None
+
+            return self._interface_cache.get_or_create(
+                bb_id=id(bb),
+                interface_type=metadata.interface_type,
+                readonly_fields=readonly_fields,
+                creator_func=lambda: create_view_from_protocol(
+                    bb,
+                    metadata.interface_type,
+                    readonly_fields=metadata.readonly_fields
+                )
+            )
+
+        return bb
+
+    def get_cache_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics for monitoring and debugging.
+
+        Returns:
+            Dict with current cache size, maxsize, and hit/miss counts
+        """
+        return self._interface_cache.get_stats()
     
     def _find_place_spec(self, fqn: str) -> PlaceSpec:
         """Find place spec by FQN using hierarchy"""
         parts = fqn.split('.')
-        return self._find_in_spec(self.spec, parts, is_place=True)
-    
+        result = self._find_in_spec(self.spec, parts, is_place=True)
+        if not isinstance(result, PlaceSpec):
+            raise TypeError(f"Expected PlaceSpec, got {type(result)}")
+        return result
+
     def _find_transition_spec(self, fqn: str) -> TransitionSpec:
         """Find transition spec by FQN using hierarchy"""
         parts = fqn.split('.')
-        return self._find_in_spec(self.spec, parts, is_place=False)
+        result = self._find_in_spec(self.spec, parts, is_place=False)
+        if not isinstance(result, TransitionSpec):
+            raise TypeError(f"Expected TransitionSpec, got {type(result)}")
+        return result
     
     def _find_in_spec(self, spec: NetSpec, parts: List[str], is_place: bool):
         """Recursively find place or transition in spec hierarchy"""
@@ -611,11 +740,17 @@ class NetRuntime:
 
     def _find_place_spec_by_parts(self, parts: Tuple[str, ...]) -> PlaceSpec:
         """Find a PlaceSpec using a tuple of path parts."""
-        return self._find_in_spec(self.spec, list(parts), is_place=True)
+        result = self._find_in_spec(self.spec, list(parts), is_place=True)
+        if not isinstance(result, PlaceSpec):
+            raise TypeError(f"Expected PlaceSpec, got {type(result)}")
+        return result
 
     def _find_transition_spec_by_parts(self, parts: Tuple[str, ...]) -> TransitionSpec:
         """Find a TransitionSpec using a tuple of path parts."""
-        return self._find_in_spec(self.spec, list(parts), is_place=False)
+        result = self._find_in_spec(self.spec, list(parts), is_place=False)
+        if not isinstance(result, TransitionSpec):
+            raise TypeError(f"Expected TransitionSpec, got {type(result)}")
+        return result
     
     async def start(self):
         """Start the Petri net execution"""