The clon Reference Manual

Table of Contents

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

The clon Reference Manual

This is the clon Reference Manual, version 0.0.2, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:43:28 2018 GMT+0.


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

1 Introduction

Clon is a Common Lisp library for scheduling much like cron.

It's under the MIT licence. See COPYING.

How to use it:

;;; create a stateless schedule:
(make-typed-cron-schedule :second '(member 0 10 20 30 40 50))
;;; create a scheduler that remembers the last scheduled time:
(make-scheduler *)
;;; schedule a function:
(schedule-function (lambda ()
                    (print (get-universal-time)))
                   *)
;;; unschedule the timer returned by SCHEDULE-FUNCTION:
(trivial-timers:unschedule-timer *)


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

2 Systems

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


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

2.1 clon

Author

Gábor Melis <mega@retes.hu>

Version

0.0.2

Dependencies
Source

clon.asd (file)

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 clon.asd

Location

clon.asd

Systems

clon (system)

Packages

clon-system


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

3.1.2 clon/packages.lisp

Parent

clon (system)

Location

packages.lisp

Packages

clon


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

3.1.3 clon/clon.lisp

Dependency

packages.lisp (file)

Parent

clon (system)

Location

clon.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 clon-system

Source

clon.asd

Use List

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

4.2 clon

Source

packages.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

clon

Source

clon.lisp (file)


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

5.1.2 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

clon

Source

clon.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

clon

Source

clon.lisp (file)

Function: make-scheduler SCHEDULE &key NOW ALLOW-NOW-P 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.

Package

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.lisp (file)

Function: schedule-function FUNCTION SCHEDULER &key NAME 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.

Package

clon

Source

clon.lisp (file)


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

5.1.3 Generic functions

Generic Function: next-time SCHEDULE &key NOW 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 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*

Package

clon

Source

clon.lisp (file)

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

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

5.1.4 Classes

Class: cron-schedule ()

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

Package

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.lisp (file)

Function: days-of-month DECODED-TIME

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

Package

clon

Source

clon.lisp (file)

Function: decode-universal-time* TIME

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

Package

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.lisp (file)

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

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

Package

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.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

clon

Source

clon.lisp (file)


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

5.2.2 Generic functions

Generic Function: bumpers OBJECT
Package

clon

Methods
Method: bumpers (CRON-SCHEDULE cron-schedule)

The bumpers in decoded time component order.

Source

clon.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
clon.asd: The clon<dot>asd file
clon/clon.lisp: The clon/clon<dot>lisp file
clon/packages.lisp: The clon/packages<dot>lisp file

F
File, Lisp, clon.asd: The clon<dot>asd file
File, Lisp, clon/clon.lisp: The clon/clon<dot>lisp file
File, Lisp, clon/packages.lisp: The clon/packages<dot>lisp file

L
Lisp File, clon.asd: The clon<dot>asd file
Lisp File, clon/clon.lisp: The clon/clon<dot>lisp file
Lisp File, clon/packages.lisp: The clon/packages<dot>lisp file

Jump to:   C   F   L  

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

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
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

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
Class, cron-schedule: Exported classes
clon: The clon system
clon: The clon package
clon-system: The clon-system package
cron-schedule: Exported classes

P
Package, clon: The clon package
Package, clon-system: The clon-system package

S
System, clon: The clon system

Jump to:   C   P   S