The cl-schedule Reference Manual

Table of Contents

The cl-schedule Reference Manual

This is the cl-schedule Reference Manual, version 0.0.5, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:07:10 2021 GMT+0.

1 Systems

The main system appears first, followed by any subsystem dependency.

1.1 cl-schedule

Authors

Gábor Melis <mega@retes.hu>
Jin-Cheng Guu <jcguu95@gmail.com>

License

MIT

Description

cl-schedule is a cron-like scheduling library in
common-lisp. It subsumes and replaces traditional cron managers thanks to richer expressiveness of Lisp.

Version

0.0.5

Dependencies

• bordeaux-threads
• trivial-timers
• local-time

Source

cl-schedule.asd (file)

Component

src (module)

2 Modules

Modules are listed depth-first from the system components tree.

2.1 cl-schedule/src

Parent

cl-schedule (system)

Location

src/

Components

• package.lisp (file)
• user.lisp (file)
• cl-schedule.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-schedule.asd

Location

cl-schedule.asd

Systems

cl-schedule (system)

3.1.2 cl-schedule/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-schedule

3.1.3 cl-schedule/src/user.lisp

Parent

src (module)

Location

src/user.lisp

Exported Definitions

• dry-run (macro)
• schedule-lambda (macro)

3.1.4 cl-schedule/src/cl-schedule.lisp

Parent

src (module)

Location

src/cl-schedule.lisp

Exported Definitions

• *default-next-time-limit* (special variable)
• cron-schedule (class)
• find-decoded-time-component-by-type (function)
• make-cron-schedule (function)
• make-scheduler (function)
• make-typed-cron-bumper (function)
• make-typed-cron-schedule (function)
• next-time (generic function)
• next-time (method)
• schedule-function (function)

Internal Definitions

• bump-day-of-month-and-day-of-week (function)
• bump-decoded-time (function)
• bump-lowest-component (function)
• bumper-index->component-index (function)
• bumpers (method)
• days-of-month (function)
• decode-universal-time* (function)
• encode-universal-time* (function)
• lowest-component-index-with-a-bumper (function)
• max-valid-decoded-time-component (function)
• min-valid-decoded-time-component (function)
• next-bump (function)
• valid-decoded-time-compenent-p (function)
• zero-decoded-time-below (function)

4 Packages

Packages are listed by definition order.

4.1 cl-schedule

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *default-next-time-limit* (special variable)
• cron-schedule (class)
• dry-run (macro)
• find-decoded-time-component-by-type (function)
• make-cron-schedule (function)
• make-scheduler (function)
• make-typed-cron-bumper (function)
• make-typed-cron-schedule (function)
• next-time (generic function)
• next-time (method)
• schedule-function (function)
• schedule-lambda (macro)

Internal Definitions

• bump-day-of-month-and-day-of-week (function)
• bump-decoded-time (function)
• bump-lowest-component (function)
• bumper-index->component-index (function)
• bumpers (generic function)
• bumpers (method)
• days-of-month (function)
• decode-universal-time* (function)
• encode-universal-time* (function)
• lowest-component-index-with-a-bumper (function)
• max-valid-decoded-time-component (function)
• min-valid-decoded-time-component (function)
• next-bump (function)
• valid-decoded-time-compenent-p (function)
• zero-decoded-time-below (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *default-next-time-limit*

The default time limit for NEXT-TIME searches.

Package

cl-schedule

Source

cl-schedule.lisp (file)

5.1.2 Macros

Macro: dry-run N &optional SCHEDULE-DEFINITION

Dry-run N times for the schedule defined by the SCHEDULE-DEFINITION.

Package

cl-schedule

Source

user.lisp (file)

Macro: schedule-lambda &key NAME FORM TIME

Package

cl-schedule

Source

user.lisp (file)

5.1.3 Functions

Function: find-decoded-time-component-by-type TYPE VALUE DECODED-TIME N

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: make-scheduler SCHEDULE &key INIT-TIME ALLOW-NOW-P LIMIT

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: schedule-function FUNCTION SCHEDULER &key NAME THREAD IGNORE-SKIPPED IMMEDIATE

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.

If IMMEDIATE is NON-NIL, call the FUNCTION immediately after this function is called. Otherwise, call the FUNCTION at the next time given by the SCHEDULER.

If IGNORE-SKIPPED is NON-NIL, ignore the skipped jobs and emits warnings accordingly. Otherwise, call the FUNCTION immediately
for each skipped instance. IGNORE-SKIPPED is by default set as
NIL for backward compatibility.

Package

cl-schedule

Source

cl-schedule.lisp (file)

5.1.4 Generic functions

Generic Function: next-time SCHEDULE &key INIT-TIME ALLOW-NOW-P 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 INIT-TIME, else it is usually INIT-TIME + the resolution of the schedule. The default value of INIT-TIME is (GET-UNIVERSAL-TIME), ALLOW-NOW-P is NIL and LIMIT is *DEFAULT-NEXT-TIME-LIMIT*

Package

cl-schedule

Source

cl-schedule.lisp (file)

Methods

Method: next-time (SCHEDULE cron-schedule) &key INIT-TIME ALLOW-NOW-P LIMIT

5.1.5 Classes

Class: cron-schedule ()

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• next-time (method)
• bumpers (method)

Direct slots

Slot: bumpers

The bumpers in decoded time component order.

Initargs

:bumpers

Readers

bumpers (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: bump-decoded-time TIME N &optional M

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: bump-lowest-component BUMPERS TIME

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: days-of-month DECODED-TIME

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: decode-universal-time* TIME

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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*.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: lowest-component-index-with-a-bumper BUMPERS

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: min-valid-decoded-time-component N

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: 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.

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: valid-decoded-time-compenent-p N VALUE

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

Function: zero-decoded-time-below DECODED-TIME N

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

Package

cl-schedule

Source

cl-schedule.lisp (file)

5.2.2 Generic functions

Generic Function: bumpers OBJECT

Package

cl-schedule

Methods

Method: bumpers (CRON-SCHEDULE cron-schedule)

The bumpers in decoded time component order.

Source

cl-schedule.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types