ilusm.dev

daem

Daemon and service management - write PID files on start, read and remove them on exit, check whether a daemon process is still alive, register UNIX signal handlers for graceful shutdown (SIGTERM/SIGINT), config reload (SIGHUP), and custom signals (SIGUSR1), fork a child process, detach into a new session (setsid), and drive a structured service loop with configurable tick interval.

Load with: use daem

What this module does

daem provides the plumbing needed to run an ilusm program as a Unix-style background service. PID file management lets your service register itself at a known path so monitoring tools can find it. Signal handlers let you respond cleanly to SIGTERM, SIGINT, and SIGHUP without hard-killing the process. The daerun orchestrator ties everything together: write the PID file, register signals, call your start hook, then spin in a tick loop until a signal sets the running flag to false, then call cleanup and remove the PID file.

All functions are also available via the daem namespace object.

Quick example

use daem

# Run as a structured daemon
daerun({
    pid: "/var/run/myservice.pid",
    intv: 5000,
    start: \() prn("service started"),
    tick: \() prn("heartbeat"),
    stop: \() prn("stopping"),
    hup: \() prn("reloading config"),
    cleanup: \() prn("cleaned up")
})

Functions

PID file management

daepf(path)

Writes the current process's PID to path via __sys_write_file. Returns {path, pid}. Call at startup.

daerm(pidfile)

Removes the PID file. Call at exit or after daerun returns.

daerd(path)

Reads and parses a PID from a PID file. Returns the integer PID, or nil if the file is absent or empty.

daeok(path)

Checks whether the daemon whose PID is in path is still running by sending signal 0 (kill -0). Returns tru if the process exists. Returns fls if the PID file is absent or the process is gone.

Signal handling

daesig(signal_name, fn)

Registers a handler for a UNIX signal by name, e.g. "SIGTERM", "SIGHUP", "SIGUSR1".

daesd(fn)

Shorthand for registering a SIGTERM handler - the standard graceful shutdown signal.

daerld(fn)

Shorthand for registering a SIGHUP handler - conventionally used to reload configuration.

daeusr(fn)

Shorthand for registering a SIGUSR1 handler.

Process control

daefk()

Forks the current process via __sys_fork(). Returns the child PID in the parent and 0 in the child, following Unix convention.

daedt()

Detaches from the controlling terminal by calling setsid(). Use after forking to become a session leader (classic double-fork daemonisation).

Service loop

daerun(opts)

Orchestrates a complete service lifecycle. opts fields:

  • pid - path to write the PID file (optional)
  • intv - tick interval in milliseconds (default 1000)
  • start - function called once before the loop begins
  • tick - function called on each loop iteration
  • stop - function called when SIGTERM or SIGINT is received
  • hup - function called on SIGHUP (config reload)
  • cleanup - function called after the loop exits
The loop runs until running.v is set to fls by a signal. Then removes the PID file and calls cleanup.

Notes

  • All operations use __sys_* host natives - requires a POSIX-compatible host.
  • Also available via the daem namespace: daem.pid, daem.rm, daem.rd, daem.ok, daem.sig, daem.run, daem.fork.
  • Requires txt and tim.