From 1c29a1983bd6339525496b40de5b91481c459bec Mon Sep 17 00:00:00 2001 From: Laksh Agarwal Date: Fri, 13 Nov 2026 01:28:05 -0500 Subject: [PATCH] Add a section on alarms to the CSP Node docs Explain what alarms are for and document the full alarm API in one place: declaring alarms, csp.schedule_alarm with a timedelta or a datetime, the handle it returns, csp.reschedule_alarm and csp.cancel_alarm (neither was documented before), how ticks scheduled for the same time are processed, and the errors raised. Includes an example node that detects a stale input with a timeout alarm. Also fill in the Alarm entry in the glossary. Fixes #130 Signed-off-by: Laksh Agarwal --- docs/wiki/concepts/CSP-Node.md | 43 ++++++++++++++++++++++++++++++++ docs/wiki/references/Glossary.md | 3 ++- 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/wiki/concepts/CSP-Node.md b/docs/wiki/concepts/CSP-Node.md index 18292a133..6baf689f1 100644 --- a/docs/wiki/concepts/CSP-Node.md +++ b/docs/wiki/concepts/CSP-Node.md @@ -2,6 +2,7 @@ - [Table of Contents](#table-of-contents) - [Anatomy of a `csp.node`](#anatomy-of-a-cspnode) +- [Alarms](#alarms) - [Basket inputs](#basket-inputs) - [Node Outputs](#node-outputs) - [Basket Outputs](#basket-outputs) @@ -103,6 +104,48 @@ Valid means that an input has had at least one tick and so it has a "current val 27\) We tick our running "sum" as an output here every second. +## Alarms + +A node only executes when one of its inputs ticks. Alarms let a node schedule its own future ticks, for timers, delays, timeouts, or work that should run periodically. +An alarm is a time series that belongs to the node: each instance of the node gets its own alarms, and only that node can schedule them. + +Alarms are declared in the `csp.alarms()` context with `csp.alarm(typ)`, where `typ` is the type of the alarm's values. +Once declared, an alarm behaves like any other input: `csp.ticked(alarm)` is true when it ticks, its name gives its current value, and `csp.valid` and `csp.num_ticks` work as for inputs. + +Alarms are scheduled with three functions, which can be called in the node body or in the `csp.start()` block: + +- **`csp.schedule_alarm(alarm, time, value)`**: schedule the alarm to tick with `value`. + `time` is either a `timedelta` from the current engine time or a `datetime`. + It returns a handle for the scheduled tick. + An alarm can have any number of ticks scheduled. Ticks scheduled for the same time are processed in consecutive engine cycles at that time, in the order they were scheduled, so `timedelta()` schedules a tick in the next engine cycle at the current time. + Scheduling a tick in the past raises a `ValueError`. +- **`csp.reschedule_alarm(alarm, handle, time)`**: move a scheduled tick to a new time, keeping its value. + It returns a new handle, and the old handle can no longer be used. + Raises a `ValueError` if the tick has already happened or was cancelled. +- **`csp.cancel_alarm(alarm, handle)`**: cancel a scheduled tick. + Does nothing if the tick has already happened or was cancelled. + +For example, this node reports when its input has not ticked for `timeout`. Every tick of `x` cancels the pending timeout and schedules a new one: + +```python +@csp.node +def stale(x: ts[float], timeout: timedelta) -> ts[bool]: + with csp.alarms(): + a_timeout = csp.alarm(bool) + + with csp.state(): + s_handle = None + + if csp.ticked(x): + if s_handle is not None: + csp.cancel_alarm(a_timeout, s_handle) # does nothing if the alarm already ticked + s_handle = csp.schedule_alarm(a_timeout, timeout, True) + elif csp.ticked(a_timeout): + return True +``` + +With `timeout=timedelta(seconds=5)` and `x` ticking at 1, 2, 3 and 10 seconds, `stale` ticks `True` at 8 and 15 seconds. + ## Basket inputs In addition to single time-series inputs, a node can also accept a **basket** of time series as an argument. diff --git a/docs/wiki/references/Glossary.md b/docs/wiki/references/Glossary.md index 6ab953bb1..0d569dd74 100644 --- a/docs/wiki/references/Glossary.md +++ b/docs/wiki/references/Glossary.md @@ -63,7 +63,8 @@ The current time of the engine can be accessed at any time within a `csp.node` b ### Alarm - +A time series that a node declares in its `csp.alarms()` block and schedules itself with `csp.schedule_alarm`, to tick at a later time. +Alarms are used for timers, delays and timeouts inside a node. See [Alarms](CSP-Node#alarms). ### Adapter