Early detection

Author: edwardalee

blog/2025-08-13-deadlines.md

@@ -170,6 +170,91 @@ Some care is needed in this case because the code generator inserts a `NetworkSe
 This is a code-generated Lingua Franca file for the `spa` federate alone.
 In this case, the reaction in the `NetworkSender` will have the same level as the reaction in the `Processor` and hence may get delayed, causing the deadline to be missed at the `pa` federate.
 
+## Early Deadline Violation Detection
+
+A deadline violation handler is invoked when a reaction is to be _started_ late.
+Above, we explained how to react to a late _completion time_ of a reaction, but that reaction is not invoked until the reaction actually completes.
+What if you need to react as soon as you know that the completion time will be late?
+Here we describe three complementary mechanisms that can react sooner.
+
+### Reactions that Monitor Their Execution Time
+
+The [`lf_check_deadline`](https://www.lf-lang.org/reactor-c/group__API.html#gab3a04dd0a1581844829b28686b6b3c53) function in the [reactor API](https://www.lf-lang.org/reactor-c/group__API.html) can be used to write a reaction that monitors its own execution time against a deadline and invokes its deadline violation handler as soon as it detects that the execution time has exceeded the deadline.
+This mechanism works when the reaction is _started_ on time, but when we want it to terminate its execution when it cannot _complete_ on time.
+A nice example of this is given in the [AnytimePrime.lf](https://github.com/lf-lang/playground-lingua-franca/blob/main/examples/C/src/deadlines/AnytimePrime.lf) example in the [deadline collection](https://github.com/lf-lang/playground-lingua-franca/blob/main/examples/C/src/deadlines/README.md) of the [LF playground repo](https://github.com/lf-lang/playground-lingua-franca/tree/main).
+It computes as many prime numbers as it can before exceeding a time budget and then aborts.
+
+### Watchdogs
+
+An experimental `watchdog` mechanism is available in LF and is described by
+[Asch, et al., Software-Defined Watchdog Timers for Cyber-Physical Systems](https://ieeexplore.ieee.org/document/10693560).
+A `watchdog` specifies a handler that is invoked if, after the watchdog is started using the [`lf_watchdog_start`](https://www.lf-lang.org/reactor-c/group__API.html#ga82bf2c7bd91fdf03b357914cf875dbb9) function in the [reactor API](https://www.lf-lang.org/reactor-c/group__API.html), the watchdog is not stopped or restarted within the specified amount of physical time.
+
+### Federates as Watchdogs
+
+The [decentralized coordinator](https://www.lf-lang.org/docs/next/writing-reactors/distributed-execution#decentralized-coordination) for federated execution gives a convenient mechanism for creating a form of watchdog that runs in a separate process or even on a separate machine.
+This can give a more robust detection of a failure because the watchdog monitor can be put on a separate machine from the process being monitored.
+
+Consider the following example:
+
+![FederatedWatchdog diagram](../static/img/blog/FederatedWatchdog.svg)
+
+The code for this is:
+
+```lf-c
+target C {
+  coordination: decentralized
+}
+import Sensor, Processor, Actuator from "SensorProcessorActuator.lf"
+
+reactor Monitored(exec = 10 ms) {
+  output complete:int
+  s = new Sensor()
+  p = new Processor(exec = exec)
+  a = new Actuator()
+  s.out -> p.inp
+  p.out -> a.inp
+  p.out -> complete
+}
+
+reactor Watchdog(STA: time = 50 ms) {
+  input inp:int
+  timer t(0, 200 ms)
+
+  reaction(t, inp) {=
+    if (!inp->is_present) {
+      lf_print("%s: ******* Failed to receive input on time at logical time " PRINTF_TIME,
+          lf_reactor_name(self), lf_time_logical_elapsed());
+    } else {
+      lf_print("%s: Monitor OK at logical time " PRINTF_TIME,
+          lf_reactor_name(self), lf_time_logical_elapsed());
+    }
+  =} STAA(0) {=
+    lf_print("%s: ******* Monitor received late input.", lf_reactor_name(self));
+  =}
+}
+
+federated reactor {
+  @label("exec = 60 ms")
+  m = new Monitored(exec = 60 ms)
+  @label("STA = 50 ms")
+  w = new Watchdog()
+  m.complete -> w.inp
+}
+```
+
+The `Monitored` reactor is simply a federate containing the sensor-processor-actuator chain.
+It is just like above except that it also copies the output of the processor to its own `complete` output.
+
+The `Watchdog` federate has a timer that exactly the `Sensor` timer in offset and period.
+It expects an input from the `Monitored` at each tick of this timer.
+The [`STA` parameter](https://www.lf-lang.org/docs/next/writing-reactors/distributed-execution#safe-to-advance-sta) (**safe to advance**) specifies that it is safe to advance the federate's logical time to the logical time of the timer tick when physical time exceeds that logical time plus the `STA`.
+The `STA` is set to 50 ms, so, at physical times 50 ms, 250 ms, 450 ms, etc. after the start time, if an input has not arrived, then the input will be assumed to be absent and the `Watchdog`'s reaction will be invoked.
+The reaction, therefore, just has to check whether the input is present.
+If it is, then the `Monitored` federate is alive and well and its processor output was received by the `Watchdog` within 50 ms.
+Otherwise, something has gone wrong that has led to a delay greater than 50 ms.
+
+
 ## Ongoing Research
 
 Several significant efforts are under way to improve the real-time behavior of LF and to guide scheduling using deadlines.
@@ -256,13 +341,11 @@ In this case, as with the federate execution, the deadline will be systematicall
 As with federated execution, there is a subtlety because an `EnclaveCommunication` reactor is inserted on the communication path to the enclave.
 It has two reactions separated by a logical action, so, for this particular structure, the reaction that sends data to `pa` will have the same level as the reaction in `p1`.
 
-The goal of enclaves is to achieve the same decoupling as with federates, but with all enclaves executing in the same process and communicating via shared memory.
-
-### Early Deadline Violation Detection
+Enclaves realize the equivalent of centralized coordination, which makes sense because they all run in the same process.
+However, this means that the `FederatedWatchdog` example cannot be converted as-is to use enclaves.
+A similar monitor, however, can be created using a physical connection.
 
-Watchdogs.
-
-[Asch, et al., Software-Defined Watchdog Timers for Cyber-Physical Systems](https://ieeexplore.ieee.org/document/10693560)
+The goal of enclaves is to achieve the same decoupling as with federates, but with all enclaves executing in the same process and communicating via shared memory.
 
 ## Conclusions
 

blog/src/FederatedWatchdog.lf

@@ -0,0 +1,43 @@
+/**
+ * Use of the decentralized coordinator to implement a watchdog.
+ */
+target C {
+  timeout: 1 s,
+  coordination: decentralized
+}
+import Sensor, Processor, Actuator from "SensorProcessorActuator.lf"
+
+reactor Monitored(exec = 10 ms) {
+  output complete:int
+  s = new Sensor()
+  p = new Processor(exec = exec)
+  a = new Actuator()
+  s.out -> p.inp
+  p.out -> a.inp
+  p.out -> complete
+}
+
+reactor Watchdog(STA: time = 50 ms) {
+  input inp:int
+  timer t(0, 200 ms)
+
+  reaction(t, inp) {=
+    if (!inp->is_present) {
+      lf_print("%s: ******* Failed to receive input on time at logical time " PRINTF_TIME ".",
+          lf_reactor_name(self), lf_time_logical_elapsed());
+    } else {
+      lf_print("%s: Monitor OK at logical time " PRINTF_TIME ".",
+          lf_reactor_name(self), lf_time_logical_elapsed());
+    }
+  =} STAA(0) {=
+    lf_print("%s: ******* Monitor received late input.", lf_reactor_name(self));
+  =}
+}
+
+federated reactor {
+  @label("exec = 60 ms")
+  m = new Monitored(exec = 60 ms)
+  @label("STA = 50 ms")
+  w = new Watchdog()
+  m.complete -> w.inp
+}