The cl-schedule Reference Manual

Table of Contents

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

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.


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

1 Systems

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


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

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
Source

cl-schedule.asd (file)

Component

src (module)


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

2 Modules

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


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

2.1 cl-schedule/src

Parent

cl-schedule (system)

Location

src/

Components

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

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 files   [Contents][Index]

3.1.1 cl-schedule.asd

Location

cl-schedule.asd

Systems

cl-schedule (system)


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

3.1.2 cl-schedule/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-schedule


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

3.1.3 cl-schedule/src/user.lisp

Parent

src (module)

Location

src/user.lisp

Exported Definitions

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

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

Parent

src (module)

Location

src/cl-schedule.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-schedule

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

Previous: , Up: Exported definitions   [Contents][Index]

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
Direct slots
Slot: bumpers

The bumpers in decoded time component order.

Initargs

:bumpers

Readers

bumpers (generic function)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-schedule.asd: The cl-schedule․asd file
cl-schedule/src: The cl-schedule/src module
cl-schedule/src/cl-schedule.lisp: The cl-schedule/src/cl-schedule․lisp file
cl-schedule/src/package.lisp: The cl-schedule/src/package․lisp file
cl-schedule/src/user.lisp: The cl-schedule/src/user․lisp file

F
File, Lisp, cl-schedule.asd: The cl-schedule․asd file
File, Lisp, cl-schedule/src/cl-schedule.lisp: The cl-schedule/src/cl-schedule․lisp file
File, Lisp, cl-schedule/src/package.lisp: The cl-schedule/src/package․lisp file
File, Lisp, cl-schedule/src/user.lisp: The cl-schedule/src/user․lisp file

L
Lisp File, cl-schedule.asd: The cl-schedule․asd file
Lisp File, cl-schedule/src/cl-schedule.lisp: The cl-schedule/src/cl-schedule․lisp file
Lisp File, cl-schedule/src/package.lisp: The cl-schedule/src/package․lisp file
Lisp File, cl-schedule/src/user.lisp: The cl-schedule/src/user․lisp file

M
Module, cl-schedule/src: The cl-schedule/src module

Jump to:   C   F   L   M  

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

A.2 Functions

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

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

D
days-of-month: Internal functions
decode-universal-time*: Internal functions
dry-run: Exported macros

E
encode-universal-time*: Internal functions

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

G
Generic Function, bumpers: Internal generic functions
Generic Function, next-time: Exported generic functions

L
lowest-component-index-with-a-bumper: Internal functions

M
Macro, dry-run: Exported macros
Macro, schedule-lambda: Exported macros
make-cron-schedule: Exported functions
make-scheduler: Exported functions
make-typed-cron-bumper: Exported functions
make-typed-cron-schedule: Exported functions
max-valid-decoded-time-component: Internal functions
Method, bumpers: Internal generic functions
Method, next-time: Exported generic functions
min-valid-decoded-time-component: Internal functions

N
next-bump: Internal functions
next-time: Exported generic functions
next-time: Exported generic functions

S
schedule-function: Exported functions
schedule-lambda: Exported macros

V
valid-decoded-time-compenent-p: Internal functions

Z
zero-decoded-time-below: Internal functions

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

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

A.3 Variables

Jump to:   *  
B   S  
Index Entry  Section

*
*default-next-time-limit*: Exported special variables

B
bumpers: Exported classes

S
Slot, bumpers: Exported classes
Special Variable, *default-next-time-limit*: Exported special variables

Jump to:   *  
B   S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-schedule: The cl-schedule system
cl-schedule: The cl-schedule package
Class, cron-schedule: Exported classes
cron-schedule: Exported classes

P
Package, cl-schedule: The cl-schedule package

S
System, cl-schedule: The cl-schedule system

Jump to:   C   P   S