The cl-schedule Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-schedule Reference Manual

This is the cl-schedule Reference Manual, version 0.0.6, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 04:01:23 2022 GMT+0.

Table of Contents


1 Systems

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


Previous: , Up: Systems   [Contents][Index]

1.1 cl-schedule

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

Authors

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

License

MIT

Version

0.0.6

Dependencies
  • bordeaux-threads (system).
  • trivial-timers (system).
  • local-time (system).
Source

cl-schedule.asd.

Child Component

src (module).


2 Modules

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


Previous: , Up: Modules   [Contents][Index]

2.1 cl-schedule/src

Source

cl-schedule.asd.

Parent Component

cl-schedule (system).

Child Components

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 cl-schedule/cl-schedule.asd

Source

cl-schedule.asd.

Parent Component

cl-schedule (system).

ASDF Systems

cl-schedule.


3.1.2 cl-schedule/src/package.lisp

Source

cl-schedule.asd.

Parent Component

src (module).

Packages

cl-schedule.


3.1.3 cl-schedule/src/user.lisp

Source

cl-schedule.asd.

Parent Component

src (module).

Public Interface
Internals

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

Source

cl-schedule.asd.

Parent Component

src (module).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-schedule

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

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.


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.

Macro: schedule! (&key name form time)

Schedule the FORM to be run with NAME and time spec TIME.

Package

cl-schedule.

Source

user.lisp.


5.1.3 Ordinary 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.

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.

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.

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.

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.

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.


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.

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.

Direct methods
Direct slots
Slot: bumpers

The bumpers in decoded time component order.

Initargs

:bumpers

Readers

bumpers.

Writers

This slot is read-only.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *schedules*
Package

cl-schedule.

Source

user.lisp.


5.2.2 Ordinary functions

Function: all-schedules ()
Package

cl-schedule.

Source

user.lisp.

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.

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.

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.

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.

Function: days-of-month (decoded-time)

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

Package

cl-schedule.

Source

cl-schedule.lisp.

Function: decode-universal-time* (time)

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

Package

cl-schedule.

Source

cl-schedule.lisp.

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.

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.

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.

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.

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.

Function: unschedule (schedule)
Package

cl-schedule.

Source

user.lisp.

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.

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.


5.2.3 Generic functions

Generic Reader: bumpers (object)
Package

cl-schedule.

Methods
Reader Method: bumpers ((cron-schedule cron-schedule))

The bumpers in decoded time component order.

Source

cl-schedule.lisp.

Target Slot

bumpers.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   B   D   E   F   G   L   M   N   S   U   V   Z  
Index Entry  Section

A
all-schedules: Private ordinary functions

B
bump-day-of-month-and-day-of-week: Private ordinary functions
bump-decoded-time: Private ordinary functions
bump-lowest-component: Private ordinary functions
bumper-index->component-index: Private ordinary functions
bumpers: Private generic functions
bumpers: Private generic functions

D
days-of-month: Private ordinary functions
decode-universal-time*: Private ordinary functions
dry-run: Public macros

E
encode-universal-time*: Private ordinary functions

F
find-decoded-time-component-by-type: Public ordinary functions
Function, all-schedules: Private ordinary functions
Function, bump-day-of-month-and-day-of-week: Private ordinary functions
Function, bump-decoded-time: Private ordinary functions
Function, bump-lowest-component: Private ordinary functions
Function, bumper-index->component-index: Private ordinary functions
Function, days-of-month: Private ordinary functions
Function, decode-universal-time*: Private ordinary functions
Function, encode-universal-time*: Private ordinary functions
Function, find-decoded-time-component-by-type: Public ordinary functions
Function, lowest-component-index-with-a-bumper: Private ordinary functions
Function, make-cron-schedule: Public ordinary functions
Function, make-scheduler: Public ordinary functions
Function, make-typed-cron-bumper: Public ordinary functions
Function, make-typed-cron-schedule: Public ordinary functions
Function, max-valid-decoded-time-component: Private ordinary functions
Function, min-valid-decoded-time-component: Private ordinary functions
Function, next-bump: Private ordinary functions
Function, schedule-function: Public ordinary functions
Function, unschedule: Private ordinary functions
Function, valid-decoded-time-compenent-p: Private ordinary functions
Function, zero-decoded-time-below: Private ordinary functions

G
Generic Function, bumpers: Private generic functions
Generic Function, next-time: Public generic functions

L
lowest-component-index-with-a-bumper: Private ordinary functions

M
Macro, dry-run: Public macros
Macro, schedule!: Public macros
make-cron-schedule: Public ordinary functions
make-scheduler: Public ordinary functions
make-typed-cron-bumper: Public ordinary functions
make-typed-cron-schedule: Public ordinary functions
max-valid-decoded-time-component: Private ordinary functions
Method, bumpers: Private generic functions
Method, next-time: Public generic functions
min-valid-decoded-time-component: Private ordinary functions

N
next-bump: Private ordinary functions
next-time: Public generic functions
next-time: Public generic functions

S
schedule!: Public macros
schedule-function: Public ordinary functions

U
unschedule: Private ordinary functions

V
valid-decoded-time-compenent-p: Private ordinary functions

Z
zero-decoded-time-below: Private ordinary functions

Jump to:   A   B   D   E   F   G   L   M   N   S   U   V   Z