Cron

Overview

This library supports classic cron expressions with additional field for the
seconds, plus a few extras. We'll get back to the extras later, let's start
with regular cron expressions.

Classic cron expressions.

Each expression contains 6 fields:

seconds, 0-59

minutes, 0-59

hours, 0-23

day of month, 1-31

month, 1-12 or JAN-DEC

day of week 0-6 or SUN-SAT

Each field can contain multiple values separated with commas, and/or ranges
determined by the beginning of the range, a hyphen, and the ending of the
range. For example, for the day of week, it could be MON-THU,SAT

A slash can be used to specify intervals: e.g. */5 in seconds field means
"every 5 seconds".

Each field can contain an asterisk * which means "any value".

Examples:

*/15 * 1-4 * * * : Run every 15 seconds from 1 to 4 hours;

0 */2 1-4 * * * : Run every two minutes from 1 to 4 hours;

0 0 7 * * MON-FRI : Run at 7:00 every working day;

0 30 23 30 * * : Run at 23:30 every 30th day of month.

Randomized cron expressions

It's possible to specify the time range in which a job will run certain number
of times.

For example, this:

@random:{"from":"10 * * * * *", "to":"50 * * * * *", "number":5}

means that the cron job will be fired in between of 10 and 50 seconds of every
minute, and the total number of invocations in that 40-second time window will
be approximately 5. It's not guaranteed to be exactly 5 though: might be a bit
less or more.

Another example: approximately 10 invocations in between of 08:00 and 22:00 on
working days:

mgos_cron_add

Adds cron entry with the expression expr (a null-terminated string, should
be no longer that 256 bytes) and cb as a callback.
user_data is an arbitrary pointer which will be passed to cb.
Returns cron ID.

mgos_cron_get_next_invocation

time_t mgos_cron_get_next_invocation(mgos_cron_id_t id, time_t date);

Calculate the next fire date after the specified date.

mgos_cron_is_expr_valid

bool mgos_cron_is_expr_valid(const char *expr, const char **perr);

Returns whether the given string is a valid cron expression or not. In case
of an error, if perr is not NULL, *perr is set to an error message; it
should NOT be freed by the caller.