This module may be used by including (use-modules (mcron core))
in a program. The main functions are add-job and
run-job-loop, which allow a program to create a list of job
specifications to run, and then to initiate the wait-run-wait loop
firing the jobs off at the requisite times. However, before they are
introduced two functions which manipulate the environment that takes
effect when a job runs are defined.
The environment is a set of name-value pairs which is built up
incrementally. Each time the add-job function is called, the
environment modifiers that have been accumulated up to that point are
stored with the new job specification, and when the job actually runs
these name-value pairs are used to modify the run-time environment in
effect.
When a job is run make sure the environment variable name has the value value.
This procedure causes all the environment modifiers that have been specified so far to be forgotten.
This procedure adds a job specification to the list of all jobs to run. time-proc should be a procedure taking exactly one argument which will be a UNIX time. This procedure must compute the next time that the job should run, and return the result. action should be a procedure taking no arguments, and contains the instructions that actually get executed whenever the job is scheduled to run. displayable should be a string, and is only for the use of humans; it can be anything which identifies or simply gives a clue as to the purpose or function of this job. configuration-time is the time from which the first invokation of this job should be computed. Finally, configuration-user should be the passwd entry for the user under whose personality the job is to run.
This procedure returns only under exceptional circumstances, but usually loops forever waiting for the next time to arrive when a job needs to run, running that job, recomputing the next run time, and then waiting again. However, the wait can be interrupted by data becoming available for reading on one of the file descriptors in the fd-list, if supplied. Only in this case will the procedure return to the calling program, which may then make modifications to the job list before calling the
run-job-loopprocedure again to resume execution of the mcron core.
The argument user should be a string naming a user (his login name), or an integer UID, or an object representing the user's passwd entry. All jobs on the current job list that are scheduled to be run under this personality are removed from the job list.
The argument count should be an integer value giving the number of time-points in the future to report that jobs will run as. Note that this procedure is disruptive; if
run-job-loopis called after this procedure, the first job to run will be the one after the last job that was reported in the schedule report. The report itself is returned to the calling program as a string.