Trail of Light

cl-cron is a simple library that allows you to implement a cron like thread in Lisp to run jobs at specific time intervals

cl-cron is still in version 0.1 and can grow bigger fast if people find it useful. So far cl-cron offers the following:

• Setting a file with predefined cl-cron-jobs to be loaded at cl-cron start
• Cl-cron-jobs that are started only at cl-cron boot
• Ability to start, stop and restart cl-cron
• Ability to log messages to a custom file

To install cl-cron you have to first download it from here. After extracting the file make sure you have a link to the cl-cron.asd file in your asdf central registry.

Please note that cl-cron is dependent on bordeaux-threads and uses internally a sleep function call which may not be available in some lisp implementations (the call is done only once so extending or fixing is very easy). Personally I have tested cl-cron on SBCL, so if you use it on another platform do let me know so that I can add it to the list of supported platform.

In order to create cl-cron jobs you need to call the make-cron-job function in the cron package.

make-cron-job (function-symbol &key minute step-min hour step-hour day-of-month step-dom month step-month day-of-week step-dow boot-only)

• function-symbol is the only required variable and should contain the function-symbol of the function to be called by the cl-cron. The function should not take any arguments and it should handle its own result printing mechanism
• minute defines at which minutes should the cron-job run. By default this value is :every meaning that it would run every minute (as long as step-min is not changed). You could provide a single number here like 10 to run the job on the 10th minute. Also if you would like to run job at different intervals then you simply need to provide a list such as `(5 10) which would run at the 5th and 10th minutes. Finally the function gen-list can be used to create a continuous list of single increment value i.e. (gen-list 1 4) would result in (1 2 3 4)
• step-min defines the step by which to increase the minutes value and can only be a number. It is by default 1. For example if minute is :every and step-min is 15 then the cron job would run at 15 minutes interval. This means that the above example is similar to having minute set to (0 15 30 45) and leaving step-min to its default value. step-min can work with any values of minute so for example setting minute to (1 2 3 4) and step-min to 2 is equivalent to setting minute to (1 3) and leaving step-min to 1
• hour defines the hour that the cron job is to run at. Behavior and values similar to minute variable
• step-hour defines the step by which to increase the hours value and can only be a number. Behavior and values similar to step-min variable
• day-of-month defines the day of the month on which the job will run. The values should be between 1 and 31 inclusive. Like hour and minute, you can provide lists if you choose to.
• step-dom defines the step by which to increase the day-of-month value and can only be a number. Behavior and values similar to step-min variable
• month defines the month that the cron job is to run at. The values should be between 1 and 12 inclusive with January being 1. Like hour and minute, you can provide lists if you choose to. Note that if you want to enter a single month you could use its full name as a symbol so for example for April you could enter the variable as :april
• step-month defines the step by which to increase the month value and can only be a number. Behavior and values similar to step-min variable
• day-of-week defines the day of the week on which the job will run. The values should be between 0 and 6 inclusive with Monday being 0. Like month you can provide either a list, a number or a single symbol.
• step-dow defines the step by which to increase the day-of-week value and can only be a number. Behavior and values similar to step-min variable
• boot-only flags a cl-cron job to be executed only when cl-cron is started. boot-only is by default set to nil

Please note that a cl-cron job will run if all the conditions are met at the current time. This means that if day-of-week and day-of-month are both set then they there result to the current date would be or-ed, much like a normal cron.

To start cl-cron all you need is to call the start-cron function in the cron package. The function would immediately load the file defined in the variable *cron-load-file* which is also available in the cron package. Then start-cron will run any and all jobs with their boot-only variable set. Finally start-cron will start the scheduler to run the remaining jobs

To stop cl-cron, you need to call the stop-cron function in the cron package. The function will first determine whether any jobs are running and will wait for them to finish before killing the scheduler thread. This behavior ensures that no critical job is interrupted mid way and hence minimizes possible data corruption

If you wish to start cl-cron without loading the file and without running jobs with boot-only variable set, then you should call the function restart-cron found in the cron package. The function would only start the scheduler. It is useful especially if you have stopped a running cl-cron for some maintenance and now you want to restart without boot-up sequence.

Note: all log data are sent to the file defined in the path at the variable *cron-log-file* in the cron package. To send messages to it just call log-cron-message and pass it the message you wish to log as a string and a type which should also be a string (default is the string “error”).

cl-cron is a tool that was built primarily for a personal need. I made the choice to write it in a way that is extensible, understandable and user-friendly, however I do not make the claim that I have succeeded. So The section offers some explanations of how I tend to try and get to those goals.

• License: Copyright ©2009 Mackram G. Raydan.This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.Of course, you know what that means you are free (as you should be) to modify, upgrade and use cl-cron the way you want.
• Support: To ask for help, to send feedback or to ask for features you can always send me an email to support(@-noSpam-)trailoflight.net. Please make sure that in the subject line you put something like [cl-cron] so that I can tell projects apart If you would like to support me and my work there are several ways that I would highly appreciate. They are all mentioned below in no order of preference
  • You can offer some word of mouth regarding my work and site.
  • You can offer me a project to work on.
  • You can choose to write a free piece of software for the community (do let me know).
  • You can donate some money (helps pay the bills ) through Moneybookers to my account donation@trailoflight.net.
    
    
    
• Shortcoming: cl-cron is far from perfect and so far does not work in implementations that do not have a sleep function. I intend to fix this as soon as I can so any advice on this is appreciated