CandleClock manages timers that persist even across restarts.

Core concepts

Timer

A timer is a function call that will happen at some point in the future. It always contains an MFA and either a duration, an interval or a crontab expression.

MFA

An MFA is a tuple with 3 elements: the module, the function and the arguments to pass to the function. The 3 elements of the tuple are the same as the 3 arguments you'd pass to Kernel.apply/3.

Crontab

A crontab expression can be used when you want the timer to trigger at regular dates or times, such as

• Every monday at 12 AM: 0 12 * * 1
• Every 5 minutes: */5 * * * *
• Every hour: 0 * * * *
• Every day at 5 PM: 0 17 * * *

Timers with crontabs can be given an additional time zone so 0 17 * * * for Europe/Berlin is 16:00 UTC during winter time but 15:00 UTC during summer time.

Startup behaviour

At startup, all timers that have an expired_at date in the past will be executed.

When planning the next execution time of a single timer, it will take the last execution time as the basis. However, that might lead to a timer being called multiple times directly after a long downtime.

For that reason, if :skip_if_offline is true, interval and cron timers will instead be planned to the next time it would've happened as if the earlier intervals would've been triggered as well, but they won't be called more than once at startup.

:skip_if_offline is enabled by default.

Duration and intervals

All durations and intervals are integers in the unit millisecond.

Common options

These are the common options that can be passed to call_after/3, call_interval/4 and call_crontab/4:

• :name (string) A name that makes this timer unique. Unique timers will be replaced when a new timer with the same name is created. That way, a defer can be implemented simply by always giving the same name.
• :skip_if_offline (bool, default: true) If set to false, interval and cron timers behave differently after a long downtime of the system. See also: Startup behaviour
• :max_calls (int, default: nil or 1 for duration timers) Controls the maximum amount this timer can be called before it is cancelled. Not supported in duration timers started with call_after/3.