From 9b06952ec800d74ea31e295aaa80eb105da95419 Mon Sep 17 00:00:00 2001 From: russlan23 Date: Wed, 5 Aug 2026 09:34:25 +0400 Subject: [PATCH 1/2] docs: explain replay-to-realtime transition Signed-off-by: russlan23 --- docs/wiki/concepts/Execution-Modes.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/wiki/concepts/Execution-Modes.md b/docs/wiki/concepts/Execution-Modes.md index 8a95f7d40..586729178 100644 --- a/docs/wiki/concepts/Execution-Modes.md +++ b/docs/wiki/concepts/Execution-Modes.md @@ -13,6 +13,7 @@ Since engines can run in both simulated and realtime mode, users should **always - [Table of Contents](#table-of-contents) - [Simulation Mode](#simulation-mode) - [Realtime Mode](#realtime-mode) + - [Replay Before Going Realtime](#replay-before-going-realtime) - [csp.PushMode](#csppushmode) - [Handling Duplicate Timestamps](#handling-duplicate-timestamps) - [Realtime Group Event Synchronization](#realtime-group-event-synchronization) @@ -38,6 +39,27 @@ All time based inputs such as `csp.timer` and alarms will switch to executing in As always, `csp.now()` should still be used in `csp.node` code, even when running in realtime mode. `csp.now()` will be the time assigned to the current engine cycle. +### Replay Before Going Realtime + +A realtime run can replay historical data before switching to live processing. Pass `realtime=True` and set `starttime` to a time in the past. The engine processes the interval from `starttime` to wall-clock time in simulation mode, as quickly as the input adapters can supply data. When engine time catches up to wall-clock time, the same graph switches to realtime mode. + +```python +from datetime import datetime, timedelta, timezone + +now = datetime.now(timezone.utc) + +csp.run( + my_graph, + starttime=now - timedelta(hours=1), + endtime=now + timedelta(minutes=5), + realtime=True, +) +``` + +In this example, `my_graph` replays one hour of history and then continues in realtime for approximately five minutes. Use an absolute future `endtime` when the run must remain active after the handoff; if the end time has already passed when replay finishes, the engine cannot continue into a live interval. + +The graph's historical input adapters must provide data for the replay interval. Realtime adapters begin supplying external events after the engine reaches realtime. Nodes do not need separate replay and live implementations: use `csp.now()` for engine time and `csp.in_realtime()` when behavior must explicitly depend on the current phase. + ## csp.PushMode When consuming data from input adapters there are three choices on how one can consume the data: From 3a72fef0c576930f809903fc5c0bcca6b2c249b9 Mon Sep 17 00:00:00 2001 From: russlan23 Date: Thu, 6 Aug 2026 10:54:40 +0400 Subject: [PATCH 2/2] docs: avoid repeating realtime handoff details Signed-off-by: russlan23 --- docs/wiki/concepts/Execution-Modes.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/wiki/concepts/Execution-Modes.md b/docs/wiki/concepts/Execution-Modes.md index 586729178..bf2fd2078 100644 --- a/docs/wiki/concepts/Execution-Modes.md +++ b/docs/wiki/concepts/Execution-Modes.md @@ -41,7 +41,8 @@ As always, `csp.now()` should still be used in `csp.node` code, even when runnin ### Replay Before Going Realtime -A realtime run can replay historical data before switching to live processing. Pass `realtime=True` and set `starttime` to a time in the past. The engine processes the interval from `starttime` to wall-clock time in simulation mode, as quickly as the input adapters can supply data. When engine time catches up to wall-clock time, the same graph switches to realtime mode. +To include a historical replay before the handoff described above, set `starttime` +to a time in the past while using `realtime=True`: ```python from datetime import datetime, timedelta, timezone @@ -56,7 +57,10 @@ csp.run( ) ``` -In this example, `my_graph` replays one hour of history and then continues in realtime for approximately five minutes. Use an absolute future `endtime` when the run must remain active after the handoff; if the end time has already passed when replay finishes, the engine cannot continue into a live interval. +Here, `my_graph` replays one hour of history and then runs live for approximately +five minutes. Use an absolute future `endtime` when the run must remain active +after the handoff; if it has already passed when replay finishes, no live interval +remains. The graph's historical input adapters must provide data for the replay interval. Realtime adapters begin supplying external events after the engine reaches realtime. Nodes do not need separate replay and live implementations: use `csp.now()` for engine time and `csp.in_realtime()` when behavior must explicitly depend on the current phase.