Basic periodic job
*, void (*) (void
*), void *);
*, unsigned long,
void (*) (void *),
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
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.
creates a new
Cron object that all the other
functions use. Like most of the other APIs in this project, it must be freed
when it is no longer needed.
Jobs can be scheduled with
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.
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.
start and stop the ticking, respectively.
discards all the job references and frees all memory associated with the
given instance of the
CronCreate() returns a reference to a
Cron, or NULL if it was unable to allocate memory
The other functions in this header don't return anything. They are assumed to usually work, unless their input is obviously wrong.