Next: , Previous: Guile modules, Up: Guile modules

5.1 The core module

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.

— Scheme procedure: append-environment-mods name value

When a job is run make sure the environment variable name has the value value.

— Scheme procedure: clear-environment-mods

This procedure causes all the environment modifiers that have been specified so far to be forgotten.

— Scheme procedure: add-job time-proc action displayable configuration-time configuration-user

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.

— Scheme procedure: run-job-loop . fd-list

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-loop procedure again to resume execution of the mcron core.

— Scheme procedure: remove-user-jobs user

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.

— Scheme procedure: get-schedule count

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-loop is 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.