Common Lisp Package: CLON

README:

FUNCTION

Public

FIND-DECODED-TIME-COMPONENT-BY-TYPE (TYPE VALUE DECODED-TIME N)

Return the first valid value not less than VALUE that is of TYPE.

MAKE-CRON-SCHEDULE (&KEY SECOND MINUTE HOUR DAY-OF-MONTH MONTH YEAR DAY-OF-WEEK)

Construct a cron-like scheduler from the SECOND, MINUTE, etc bumpers for components of decoded times (using the default time zone for the time being). A bumper in its most generic from a function of three arguments: the current value, the whole decoded time, and the index of the current value in the decoded time. A bumper is expected to return the smallest value that is valid for that component and not less than the current value or NIL if it cannot find a valid value. Returning a value that is smaller than the current one is the same as returning NIL. A bumper can simply be a number which is equivalent to (CONSTANTLY NUMBER). Bumpers are not allowed to depend on `lower' components of the decoded time. The allowed dependency graph is this: SECOND -> MINUTE -> HOUR -> (DAY-OF-MONTH <-> DAY-OF-WEEK) -> MONTH -> YEAR That is, the SECOND bumper may look at the whole decoded time but the MINUTE bumper may not look at seconds. DAY-OF-WEEK and DAY-OF-MONTH may depend on each other to allow specifying the 'last Friday of the month'. The resolution of the schedule is defined implicitly by the lowest bumper. NEXT-TIME always bumps the component of the decoded time that belongs to the lowest bumper before trying to find mathces if its LAST-TIME argument is not NIL. Of course, DAY-OF-WEEK is the odd one out: it is the day-of-month component that is bumped if DAY-OF-WEEK is the lowest bumper. This scheme allows (MAKE-CRON-SCHEDULE :MONTH 12) trigger only once per year instead of every second in December. For a more packed schedule one can use the symbol '* as a bumper: (MAKE-CRON-SCHEDULE :HOUR '* :MONTH 12) which makes hour the lowest bumper and the schedule triggers every hour in December. It is an error if all bumpers are NIL.

MAKE-SCHEDULER (SCHEDULE &KEY (NOW (GET-UNIVERSAL-TIME)) ALLOW-NOW-P (LIMIT *DEFAULT-NEXT-TIME-LIMIT*))

Return a `scheduler' function of no arguments that returns times from NOW on by repeatedly calling NEXT-TIME on SCHEDULE. ALLOW-NOW-P is passed to the first invocation of NEXT-TIME.

MAKE-TYPED-CRON-BUMPER (TYPE)

Return a bumper function suitable for MAKE-CRON-SCHEDULE that returns the first valid value according to TYPE. Convenience function on top of FIND-DECODED-TIME-COMPONENT-BY-TYPE.

MAKE-TYPED-CRON-SCHEDULE (&KEY SECOND MINUTE HOUR DAY-OF-MONTH MONTH YEAR DAY-OF-WEEK)

A convenience function much like MAKE-CRON-SCHEDULE but assumes that no bumper can be a function designator so it must be a number, the symbol * or a type specifier in which case it calls MAKE-TYPED-CRON-BUMPER on it providing a terser syntax.

SCHEDULE-FUNCTION (FUNCTION SCHEDULER &KEY NAME (THREAD (CURRENT-THREAD)))

Create a timer just as with TRIVIAL-TIMERS:MAKE-TIMER but schedule and reschedule FUNCTION according to SCHEDULER that is a function of no parameters that returns a universal time or NIL. The returned timer can be shut down with TRIVIAL-TIMERS:UNSCHEDULE-TIMER.

Private

BUMP-DAY-OF-MONTH-AND-DAY-OF-WEEK (DOM-BUMPER DOW-BUMPER DECODED-TIME)

Extra hair due to the circular dependency between DAY-OF-MONTH and DAY-OF-WEEK bumpers. This function rolls the two bumpers into one.

BUMP-DECODED-TIME (TIME N &OPTIONAL (M 1))

Increment the Nth component of decoded TIME, handle overflows, zero the lower components. Return changed decoded time and the highest index that was changed.

BUMP-LOWEST-COMPONENT (BUMPERS TIME)

Bump the lowest component of decoded TIME that has a bumper. Return it as a universal time.

BUMPER-INDEX->COMPONENT-INDEX (I)

Return the index of the decoded time component that is effect by bumper I. Day of week is lumped together with day of month.

DAYS-OF-MONTH (DECODED-TIME)

Return the number of days in the month DECODED-TIME.

DECODE-UNIVERSAL-TIME* (TIME)

Return the decoded time components as a list instead of multiple values.

ENCODE-UNIVERSAL-TIME* (DECODED-TIME)

Encode DECODED-TIME that is a decoded time in list form such as one that was returned by DECODE-UNIVERSAL-TIME*.

LOWEST-COMPONENT-INDEX-WITH-A-BUMPER (BUMPERS)

Return the the index of what is basically the root of current dependency graph.

MAX-VALID-DECODED-TIME-COMPONENT (N &OPTIONAL DECODED-TIME)

Return the largest valid value for the Nth component of DECODED-TIME or NIL if there is no limit. Passing DECODED-TIME is necessary only for the day of month component because the number of days in a month varies.

MIN-VALID-DECODED-TIME-COMPONENT (N)

Return the smallest valid value for the Nth decoded time component.

NEXT-BUMP (BUMPER DECODED-TIME N)

Invoke BUMPER on the Nth component of DECODED-TIME. Return its value if it can ever be valid (not necessarily in the context of DECODED-TIME) or else NIL.

VALID-DECODED-TIME-COMPENENT-P (N VALUE)

See if value can ever be a valid value as the Nth component of a decoded time.

ZERO-DECODED-TIME-BELOW (DECODED-TIME N)

Set the first N components of DECODED-TIME to their MIN-VALID-DECODED-TIME-COMPONENT values.

Undocumented

LEAP-YEARS-BEFORE (YEAR)

GENERIC-FUNCTION

Public

NEXT-TIME (SCHEDULE &KEY NOW ALLOW-NOW-P LIMIT (NOW (GET-UNIVERSAL-TIME)) (LIMIT *DEFAULT-NEXT-TIME-LIMIT*))

Return the next time according to SCHEDULE or NIL if there is no next time. If ALLOW-NOW-P the earliest possible time to be returned is NOW, else it is usually NOW + the resolution of the schedule. The default value of NOW is (GET-UNIVERSAL-TIME), ALLOW-NOW-P is NIL and LIMIT is *DEFAULT-NEXT-TIME-LIMIT*

SLOT-ACCESSOR

Private

BUMPERS (OBJECT)

The bumpers in decoded time component order.

VARIABLE

Public

*DEFAULT-NEXT-TIME-LIMIT*

The default time limit for NEXT-TIME searches.

CLASS

Public

CRON-SCHEDULE

A cron-like schedule. See MAKE-CRON-SCHEDULE for details.