forked from Telodendria/Telodendria
97 lines
2.9 KiB
Groff
97 lines
2.9 KiB
Groff
.Dd $Mdocdate: December 24 2022 $
|
|
.Dt CRON 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm Cron
|
|
.Nd Basic periodic job scheduler.
|
|
.Sh SYNOPSIS
|
|
.In Cron.h
|
|
.Ft Cron *
|
|
.Fn CronCreate "unsigned long"
|
|
.Ft void
|
|
.Fn CronOnce "Cron *" "void (*) (void *)" "void *"
|
|
.Ft void
|
|
.Fn CronEvery "Cron *" "unsigned long" "void (*) (void *)" "void *"
|
|
.Ft void
|
|
.Fn CronStart "Cron *"
|
|
.Ft void
|
|
.Fn CronStop "Cron *"
|
|
.Ft void
|
|
.Fn CronFree "Cron *"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
.Nm
|
|
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,
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
.Nm
|
|
works by "ticking" at an interval defined by the caller of
|
|
.Fn 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,
|
|
.Nm
|
|
tries to tick at constant intervals, however it is possible that
|
|
a job may overrun the tick duration. If this happens,
|
|
.Nm
|
|
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,
|
|
.Nm
|
|
is best suited for scheduling jobs that should happen
|
|
"approximately" every so often; it is not a real-time scheduler
|
|
by any means.
|
|
.Pp
|
|
.Fn CronCreate
|
|
creates a new
|
|
.Nm
|
|
object that all the other functions use. Like most of the other
|
|
APIs in this project, it must be freed with
|
|
.Fn CronFree
|
|
when it is no longer needed.
|
|
.Pp
|
|
Jobs can be scheduled with
|
|
.Fn CronOnce
|
|
and
|
|
.Fn CronEvery .
|
|
.Fn 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.
|
|
.Pp
|
|
.Fn 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.
|
|
.Pp
|
|
.Fn CronStart
|
|
and
|
|
.Fn CronStop
|
|
start and stop the ticking, respectively.
|
|
.Fn CronFree
|
|
discards all the job references and frees all memory associated
|
|
with the given instance of the
|
|
.Nm
|
|
instance.
|
|
.Sh RETURN VALUES
|
|
.Pp
|
|
.Fn CronCreate
|
|
returns a reference to a
|
|
.Nm ,
|
|
or NULL if it was unable to allocate memory for it.
|
|
.Pp
|
|
The other functions in this header don't return anything. They
|
|
are assumed to usually work, unless their input is obviously
|
|
wrong.
|