saturnin.lib.daemon

Saturnin daemon process management.

This module provides functions for starting and stopping Saturnin daemon processes, handling platform-specific behaviors for process creation and signal delivery (e.g., SIGINT on Unix, CTRL_C_EVENT on Windows).

Functions

saturnin.lib.daemon.start_daemon(args: list[str]) → int | None

Starts daemon process.

Parameters:

args (list[str]) – Arguments for subprocess.Popen (first item must be the daemon filename)

Returns:

PID for started daemon, or None if start failed.

Return type:

int | None

Note

Graceful shutdown on Windows is tricky. To allow shutdown of the daemon process via a SIGINT-like mechanism (specifically, by sending a CTRL_C_EVENT, as SIGINT is not directly available), it is necessary to start a new shell with a new console in the background for the daemon process.

saturnin.lib.daemon.stop_daemon(pid: int | str | Path) → None

Stops the daemon process by invoking saturnin-daemon script.

Parameters:

pid (int | str | Path) – PID or text file name/Path where PID is stored.

Raises:

Error – If the saturnin-daemon stop command fails or times out. The original subprocess.CalledProcessError or subprocess.TimeoutExpired (if timeout of 10 seconds is reached) will be set as the __cause__ of this Error.

Return type:

None

Important

On Linux/Unix: Sends SIGINT signal to the daemon process. On Windows: Detaches from console, attaches itself to daemon console and sends control-C event to it.

Note

Graceful shutdown on Windows is tricky. It requires that the daemon process has a console; otherwise, the CTRL_C_EVENT cannot be delivered. This condition is met if the daemon was started by start_daemon() or the saturnin-daemon script directly.