NAME

Cron — Basic periodic job scheduler.

SYNOPSIS

#include <Cron.h>

Cron *
CronCreate(unsigned long);

void
CronOnce(Cron *, void (*) (void *), void *);

void
CronEvery(Cron *, unsigned long, void (*) (void *), void *);

void
CronStart(Cron *);

void
CronStop(Cron *);

void
CronFree(Cron *);

DESCRIPTION

Cron is an extremely basic job scheduler. So basic, in fact, that it runs all jobs on a single thread, which means that it is intended for short-lived jobs. In the future, Cron might be extended to support a one-thread-per-job model, but for now, jobs should consider that they are sharing their thread, so they should not be long-running jobs.

Cron works by "ticking" at an interval defined by the caller of CronCreate(). At each tick, all the jobs are queried, and if they are due to run again, their function is executed. As much as possible, Cron tries to tick at constant intervals, however it is possible that a job may overrun the tick duration. If this happens, Cron ticks again immediately after all the jobs for the previous tick have completed. This is in an effort to compensate for the lost time, however it is important to note that when jobs overrun the tick interval, the interval is pushed back. In this way, Cron is best suited for scheduling jobs that should happen "approximately" every so often; it is not a real-time scheduler by any means.

CronCreate() creates a new Cron object that all the other functions use. Like most of the other APIs in this project, it must be freed with CronFree() when it is no longer needed.

Jobs can be scheduled with CronOnce() and CronEvery(). CronOnce() schedules a one-off job to be executed only at the next tick, and then discarded. This is useful for scheduling tasks that only have to happen once, or very infrequently depending on conditions other than the current time, but don't have to happen immediately. The caller simply indicates that it wishes for the task to execute at some time in the future. How far into the future this practically ends up being is determined by how long it takes other jobs to finish, and what the tick interval is.

CronEvery() schedules a repetitive task to be executed at approximately the given interval. As stated above, this is a fuzzy interval; depending on the jobs being run and the tick interval, tasks may not happen at exactly the scheduled time, but they will eventually happen.

CronStart() and CronStop() start and stop the ticking, respectively. CronFree() discards all the job references and frees all memory associated with the given instance of the Cron instance.

RETURN VALUES

CronCreate() returns a reference to a Cron, or NULL if it was unable to allocate memory for it.

The other functions in this header don't return anything. They are assumed to usually work, unless their input is obviously wrong.