ALARM_D

object ALARM_D adm/daemons/alarm.c

Schedules and executes recurring or one-shot events defined in the configured alarms directory (ALARMS_PATH) or registered at runtime. Re-evaluates the full alarm list once per wall-clock minute and dispatches any alarm whose pattern matches the current minute. See the alarm system for types, file format, and patterns.

inherits STD_DAEMON std/daemon/daemon.c

inherits CLASS_ALARM

variable alarms class Alarm *

variable cid int

# publicvarargs add_once

Registers a one-shot ("O" type) alarm at runtime — a thin wrapper around add_alarm() that fixes the type to "O". Throws if any of master, pattern, file, or func is null.

param master string "true" if the alarm targets the master file, anything else otherwise

param pattern string When to fire, in YY-MM-DD@HH:MM form

param file string Absolute path to the target object

param func string Function on the target to invoke

param args... mixed Optional trailing arguments handed to the target function

returns int 1 on success, 0 if the alarm failed validation

# publicvarargs add_alarm

Registers an alarm of any type at runtime. Builds and validates the alarm, appends it to the in-memory list, and persists it. Throws if any of type, master, pattern, file, or func is null. Note that reload_alarms() discards any alarm not present on disk.

param type string One-character alarm type (O, H, D, W, M, Y); B alarms must come from config files

param master string "true" if the alarm targets the master file

param pattern string Pattern string in the format for the given type

param file string Absolute path to the target object

param func string Function on the target to invoke

param args... mixed Optional trailing arguments

returns int 1 on success, 0 if the alarm failed validation

# public remove_alarm

Removes an alarm by its generated id and persists the change.

param id string The alarm id assigned in create_alarm()

returns int 1 if an alarm was removed, 0 if none matched

# public find_alarm_by_id

Looks up a single alarm by its unique id.

param id string The alarm id to search for

returns class Alarm The matching alarm, or null if not found

# public query_alarms

Returns all currently registered alarms.

returns class Alarm * The full alarm list

# public reload_alarms

Rebuilds the in-memory list from disk — clears the current alarms, scans ALARMS_PATH for *.txt files, parses each, and persists the result. Discards any alarms added at runtime.

returns void

# public create_alarm

Builds and validates an alarm from parsed parts in the order ({ type, pattern, master, file, func, args... }). Assigns a UUID-based id. Returns null if the parts list is too short or validation fails.

param parts string * The parsed config line — at least 5 elements

param silent int When non-zero, validation failures return null quietly instead of throwing

returns class Alarm The constructed alarm, or null

# public calculate_alarm_time

Computes the next execution time for an alarm based on its type and pattern.

param alarm class Alarm The alarm to calculate for

param next int 1 to force the strictly-future occurrence, 0 to allow the current minute

returns int Unix timestamp of the next execution, or -1 on error

# public validate_alarm

Validates an alarm: target file exists and loads, target function exists, and (for "O" alarms) the time is not in the past.

param alarm class Alarm The alarm to validate

param silent int 0 to throw on failure, 1 to log and return 0

returns int 1 if valid, 0 if invalid

# public time_to_next_poll

Reports how long until the next scheduled poll.

returns int Seconds until the next poll, or -1 if none is scheduled

# public poll_alarms

The scheduling engine. Re-schedules itself for the start of the next minute, then fires every alarm whose occurrence falls in the current minute and has not already run, cleaning up expired one-shots.

returns void

# public execute_boot_alarms

Handler for SIG_SYS_BOOT. Schedules every "B" (Boot) alarm to run after its configured seconds-after-boot delay. Rejects callers other than the signal daemon.

returns void

# private execute_alarm

Loads an alarm’s target file and invokes its handler with the alarm’s arguments. Any failure is logged to system/alarm rather than propagated.

param alarm class Alarm The alarm to execute

returns void