6.6 The Watchdog and Timeout Extension

4 min read

Two notification fields let a running service adjust the deadlines it is held to. Both are authenticated exactly as any other notification (§10.5), and both carry microseconds.

6.6.1 The watchdog #

WatchdogTimeout sets the interval peinit expects WATCHDOG=1 pings at. Zero, the default, disables it. Missing a ping is a WatchdogTimeout cause and takes the ordinary restart path.

A service may change the interval at runtime by sending WATCHDOG_USEC=<value>:

• A value greater than zero updates the interval and re-arms immediately — the current timer is cancelled and a fresh one starts from the moment the message was received, rather than the new interval applying only from the next ping.
• A value of zero disables the watchdog entirely, equivalent to WatchdogTimeout=0.

The runtime value does not persist. On a restart the interval reverts to the definition's WatchdogTimeout converted to microseconds, and if that is zero the watchdog starts disabled whatever the previous incarnation had set.

WATCHDOG_USEC is honoured only while the service is Active. A service that sends it while still Starting — before its own READY=1 — is ignored and gets the definition's value.

6.6.2 Timeout extension #

A service may ask for more time during a start, stop or reload by sending EXTEND_TIMEOUT_USEC=<value>.

peinit sets the current phase's deadline to expire that many microseconds from now. The extension replaces the deadline rather than adding to it — each message sets an absolute deadline computed from its own arrival — and may be sent repeatedly.

Because it replaces, a small value shortens the remaining time rather than being ignored, and a value of zero sets the deadline to now.

6.6.2.1 The caps #

The extended deadline cannot exceed four times the phase's base timeout:

A value beyond the cap is clamped, not rejected — the message succeeds and the deadline becomes the maximum permitted. Because the cap is anchored to when the operation started rather than to the previous deadline, repeated messages cannot creep past it.

During shutdown an additional cap applies: the deadline cannot exceed the time remaining in the global ShutdownTimeout, and where both caps apply the stricter wins.

6.6.2.2 Where it does not apply #

A message arriving while the service is in a non-transitional state — Active, Completed, Failed — is ignored. There is no deadline to extend.

During shutdown, as at any other time, an extension moves only a deadline the service already has. A service still in a transition when the shutdown begins — starting, reloading, or stopping under an explicit stop — extends that transition's deadline, and one already stopping keeps its stop deadline, extension included, into its wave (§12.2). A service that is Active until its stop wave reaches it has no deadline to extend before then, so a request it sends earlier is ignored like any other in a non-transitional state. A service that expects its stop to take longer sends the request once its stop has begun.

Edit this page