Scheduler
Server Smalltalk provides a scheduler function that is a Smalltalk equivalent of the Unix cron(1) utility. This scheduler allows automatic, repetitive scheduling of events, such as on the first of the month, or every Sunday, or every 5 seconds, or every 5 seconds when the first day of the month is a Sunday. It also supports scheduling events to be run at a given moment such as 3:05 p.m. on Jan 1, 2014.
The scheduling function consists of 3 classes, SstCron, SstCronEntry, and SstCronEvent.
SstCronEntry
SstCronEntry is used to create a scheduling entry with a set of scheduling time constraints and a block (the unit of work to be performed). The constraints can have three possible types of values:
nil
The constraint is true for any possible value (the default).
collection
true for any value in the collection within the limits of the constraint (an exception is raised for values outside the limits)
integer
true for all multiples of the integer within the limits of the constraint
An entry is considered to be enabled when it is added to the SstCron instance and ready-to-run when all of its constraints are met.
Class methods
at:do:
This is a shortcut for SstCronEntry new date: aDateAndTime; workBlock: aBlock; yourself used to create a one-time event entry.
Instance methods
cronName:
Set the receiver's name attribute to @aName.
date:
Set the date and time upon which the receiver's %workBlock should be executed. This will be a once-only execution. This constraint should not be specified together with any of the other constraints.
days:
Set the receiver's day constraint. If @d is nil then the day is unconstrained. If @d is an integer, then all multiples between 1 and 31 will be used. Otherwise @d should be a collection of integers.
daysOfWeek:
Set the receiver's day-of-week constraint. If @dow is nil then the day is unconstrained. If @dow is an integer, then all multiples between 1 and 7 will be used. Otherwise @dow should be a collection of integers. Note that 1 = Sunday, 2 = Monday, ... 7 = Saturday.
hours:
Set the receiver's hours constraint. If @hours is nil then the hour is unconstrained. If @hours is an integer, then all multiples between 0 and 23 will be used. Otherwise @hours should be a collection of integers.
minutes:
Set the receiver's minutes constraint. If @minutes is nil then the minutes is unconstrained. If @minutes is an integer, then all multiples between 0 and 59 will be used. Otherwise @minutes should be a collection of integers.
months:
Set the receiver's months constraint. If @m is nil then the month is unconstrained. If @m is an integer, then all multiples between 1 and 12 will be used. Otherwise @m should be a collection of integers.
seconds:
Set the receiver's seconds constraint. If @s is nil then the second is unconstrained. If @s is an integer, then all multiples between 0 and 59 will be used. Otherwise @s should be a collection of integers.
workBlock:
Sets the receiver’s workBlock attribute to @aBlock.
SstCronEvent
SstCronEvent is an internal class used to hold scheduled events. It has no API methods.
SstCronSstCron does the actual scheduling of SstCronEntrys based on their constraint values. Entries are scheduled by adding an SstCronEntry to the SstCron object (obtained with SstCron default) using add:, and stopped by removing the entry using remove: (once-only entries will be automatically removed after they run). Entries are automatically requeued to run at the next time satisfying its constraints. The entry is requeued only after it has finished executing. Thus an entry registered to execute every second that takes five seconds to run will only be run every five seconds; there will not be multiple simultaneous executions.
Class methods
default
Answers the SstCron singleton.
Instance methods
add:
Cause @entry to be scheduled. Answer the entry.
entryNamed:
Answer a CronEntry named @aName or nil if not found.
remove:
Remove @entry from the scheduler. Answer the entry if found or nil if it was not scheduled.
It's easiest to show how to use SstCron and SstCronEntry with some examples:
"Primitive clock on the Transcript's title bar, updating every 5 seconds.
Inspecting the entry will show %seconds was expanded to
(0 5 10 15 20 25 30 35 40 45 50 55)
In Smalltalk terms this is (0 to: 59 by: 5). So specifying a single
number really means: (minValue to: maxValue by: number). The entry
is named so that it can be found later."
SstCron default add:
(SstCronEntry new
workBlock: [Transcript shell title: Time now printString];
seconds: 5;
cronName: ‘Transcript clock’;
yourself)
“Stop running the clock on the Transcript title bar.”
(SstCron default entryNamed: ‘Transcript clock’) ifNotNil: [ :anEntry |
SstCron remove: anEntry ]
"Run a backup every Sunday at midnight. Note that midnight (00:00:00)is regarded to be morning. Also note that it's important to specify the
hours, minutes and seconds: otherwise they default to nil which means
match every possible value. So without them explicitly specified you'd
be running this event repeatedly all day! We don't set the month or day
because we want them to always match."
SstCron default add:
(SstCronEntry new
workBlock: ["perform backup"];
daysOfWeek: #(1);
hours: #(0);
minutes: #(0);
seconds: #(0);
yourself)
"Run ‘foo’ on the first Monday of the month at noon. There can only be
one day from the 1st to the 7th that's a Monday."
SstCron default add:
(SstCronEntry new
workBlock: [“perform foo”];
days: (1 to: 7);
daysOfWeek: #(2);
hours: #(12);
minutes: #(0);
seconds: #(0);
yourself)
"This should be obvious"
SstCron default add:
(SstCronEntry
at: (DateAndTime year: 2000 month: 1 day: 1 hour: 0 minute: 0 second: 0)
do: [Transcript shell title: 'Happy New Year!'])