telodendria/include/Cytoplasm/Cron.h
Jordan Bancino 461357b526 Move headers from src/include to include/Cytoplasm.
This makes it easier to build Cytoplasm as a component of another
program (for example, Telodendria), or as a standalone system library.
2024-01-13 18:40:31 -05:00

140 lines
4.8 KiB
C

/*
* Copyright (C) 2022-2024 Jordan Bancino <@jordan:bancino.net>
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge,
* publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#ifndef CYTOPLASM_CRON_H
#define CYTOPLASM_CRON_H
#include <stdint.h>
/***
* @Nm Cron
* @Nd Basic periodic job scheduler.
* @Dd December 24 2022
*
* This is an extremely basic job scheduler. So basic, in fact, that
* it currently runs all jobs on a single thread, which means that it
* is intended for short-lived jobs. In the future, it might be
* extended to support a one-thread-per-job model, but for now, jobs
* should take into consideration the fact that they are sharing their
* thread, so they should not be long-running.
* .Pp
* .Nm
* works by ``ticking'' at an interval defined by the caller of
* .Fn CronCreate .
* At each tick, all the registered 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 one
* or more jobs 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 lost time,
* however it is important to note that when jobs overrun the tick
* interval, the interval is pushed back by the amount that it was
* overrun. Because of this,
* .Nm
* is best suited for scheduling jobs that should happen
* ``aproximately'' every so often; it is not a real-time scheduler
* by any means.
*/
/**
* All functions defined here operate on a structure opaque to the
* caller.
*/
typedef struct Cron Cron;
/**
* A job function is a function that takes a void pointer and returns
* nothing. The pointer is passed when the job is scheduled, and
* is expected to remain valid until the job is no longer registered.
* The pointer is passed each time the job executes.
*/
typedef void (JobFunc) (void *);
/**
* Create a new
* .Nm
* object that all other functions operate on. Like most of the other
* APIs in this project, it must be freed with
* .Fn CronFree
* when it is no longer needed.
* .Pp
* This function takes the tick interval in milliseconds.
*/
extern Cron * CronCreate(uint64_t);
/**
* Schedule a one-off job to be executed only at the next tick, and
* then immediately 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 for
* other registered jobs to finish, and what the tick interval is.
* .Pp
* This function takes a job function and a pointer to pass to that
* function when it is executed.
*/
extern void
CronOnce(Cron *, JobFunc *, void *);
/**
* Schedule a repetitive task to be executed at aproximately the given
* interval. As stated above, this is as fuzzy interval; depending on
* the jobs being run and the tick interval, tasks may not execute at
* exactly the scheduled time, but they will eventually execute.
* .Pp
* This function takes an interval in milliseconds, a job function,
* and a pointer to pass to that function when it is executed.
*/
extern void
CronEvery(Cron *, uint64_t, JobFunc *, void *);
/**
* Start ticking the clock and executing registered jobs.
*/
extern void
CronStart(Cron *);
/**
* Stop ticking the clock. Jobs that are already executing will
* continue to execute, but when they are finished, no new jobs will
* be executed until
* .Fn CronStart
* is called.
*/
extern void
CronStop(Cron *);
/**
* Discard all job references and free all memory associated with the
* given
* .Nm Cron
* instance.
*/
extern void
CronFree(Cron *);
#endif /* CYTOPLASM_CRON_H */