pacer.py
1"""Turn-based pacing: the market waits while the Agent works, then moves to its next turn.23In a turn-based Agent experiment the shared clock never moves with real time. The4TurnPacer, a thread in the owning process, advances it. It moves the clock only when the5whole experiment is settled at the current time:67- the execution owner has processed every market event up to it;8- the Runtime has received every market notification published so far;9- the Runtime has fully stepped at this time, so any work that was due or triggered has10 already started; and11- the Agent has no work running and no model reply outstanding.1213An order or cancel the Agent submits while the market waits is stamped with the current14time, and the owner executes commands stamped before its clock. So whenever commands are15pending, the pacer moves the clock on by one nanosecond: the command executes at the same16instant, and the Agent gets its result without the market moving.1718Then it jumps to the earliest of: the Runtime's next own time (scheduled work, a wait,19a retry, the end), the next market event, or the experiment end. The execution owner20processes every event in between in order, exactly as in Live mode. While the Agent21works, market time stands still, so its thinking and model latency cost nothing.2223A model request whose reply has not arrived within the attempt timeout in real time is24given its deadline: the clock jumps to it so the Runtime times the attempt out.25"""2627from __future__ import annotations28import logging2930import time31from threading import Event, Thread32from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Tuple3334_log = logging.getLogger(__name__)3536if TYPE_CHECKING: # Annotation only.37 from sim_platform.experiments.execution.session import ExperimentSession38 from sim_platform.experiments.scheduling.clock import SharedExperimentClock3940# How often the pacer looks at the experiment (seconds).41POLL_SECONDS = 0.00242TERMINAL = ('completed', 'stopped', 'failed')43# Attempt states with a model reply still outstanding.44WAITING_FOR_MODEL = ('running', 'expiry_pending')454647class TurnPacer:48 """Advance a turn-based experiment clock between the Agent's turns.4950 Args:51 clock: The experiment's turn-based SharedExperimentClock (paced=True).52 session: The execution owner whose market events the clock releases.53 runtime: Returns the Runtime's latest published snapshot.54 published: Returns how many market notification batches have been published55 to the Runtime.56 timeout_ns: The model attempt timeout, applied in real time while paced.57 """5859 def __init__(60 self,61 clock: SharedExperimentClock,62 session: ExperimentSession,63 runtime: Callable[[], Dict[str, Any]],64 published: Callable[[], int],65 timeout_ns: int,66 ) -> None:67 self.clock, self.owner = clock, session68 self._runtime, self._published = runtime, published69 self._timeout_ns = timeout_ns70 self._stop = Event()71 self._thread: Optional[Thread] = None72 # (attempt id, real time it was first seen outstanding).73 self._outstanding: Optional[Tuple[str, int]] = None74 self.turns = 075 self.error: Optional[BaseException] = None7677 def start(self) -> None:78 if self._thread is None:79 self._thread = Thread(target=self._run, name='turn-pacer', daemon=True)80 self._thread.start()8182 def stop(self) -> None:83 self._stop.set()84 if self._thread is not None and self._thread.is_alive():85 self._thread.join(timeout=1)8687 def _run(self) -> None:88 try:89 while not self._stop.is_set():90 if self.owner.snapshot()['state'] in TERMINAL:91 return92 target = self.next_target()93 if target is not None:94 self.clock.advance_to(target)95 self.turns += 196 self.owner.wake()97 else:98 self._stop.wait(POLL_SECONDS)99 except BaseException as exc: # Surfaced through snapshot(); the run then stalls visibly.100 _log.warning('Handled failure in _run', exc_info=True)101 self.error = exc102103 def next_target(self) -> Optional[int]:104 """The time to advance to now, or None while the experiment is not settled."""105 if self.owner.snapshot()['state'] != 'running':106 return None107 now = self.clock.target_ns()108 end = self.owner.end_ns109 if now >= end:110 return None111 timeline, reader = self.owner.timeline, self.owner.reader112 upcoming = (113 reader.event_time(timeline.cursor)114 if timeline.cursor < reader.manifest['frames']115 else None116 )117 if upcoming is not None and upcoming < now:118 return None # The owner is still processing market events before now.119 if upcoming == now:120 # Like commands, an event executes once the clock is past its time.121 return now + 1122 if self.owner.sequencer.queued_at_or_after(now):123 # The owner executes commands stamped before the current time; one nanosecond124 # lets the Agent's order or cancel made at this instant execute now, while it125 # waits for the result.126 return now + 1127 if self.owner.sequencer.snapshot()['pending']:128 return None # A command is executing; its result reaches the Agent next.129 runtime = self._runtime()130 stepped = runtime.get('stepped_ns')131 if stepped is None or int(stepped) < now:132 return None133 if int(runtime.get('event_sequence', 0)) < self._published():134 return None135 attempt = runtime.get('attempt') or {}136 if attempt.get('state') in WAITING_FOR_MODEL:137 return self._model_deadline(attempt)138 self._outstanding = None139 if attempt.get('state') == 'retrying' and attempt.get('retry_due_ns') is not None:140 return max(now + 1, int(attempt['retry_due_ns']))141 if (runtime.get('work') or {}).get('state') == 'running':142 return None143 times = [end]144 if runtime.get('next_ns') is not None:145 times.append(int(runtime['next_ns']))146 if upcoming is not None:147 times.append(upcoming)148 later = [t for t in times if t > now]149 return min(later) if later else None150151 def _model_deadline(self, attempt: Dict[str, Any]) -> Optional[int]:152 """The attempt's deadline once it has been outstanding longer than the timeout."""153 identity = str(attempt.get('attempt_id'))154 started = time.monotonic_ns()155 if self._outstanding is None or self._outstanding[0] != identity:156 self._outstanding = (identity, started)157 return None158 if started - self._outstanding[1] < self._timeout_ns or attempt.get('deadline_ns') is None:159 return None160 return int(attempt['deadline_ns'])161162 def snapshot(self) -> Dict[str, Any]:163 return dict(turns=self.turns, error=repr(self.error) if self.error else None)