The clerk Reference Manual

Table of Contents

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

The clerk Reference Manual

This is the clerk Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:22:53 2022 GMT+0.


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

1 Introduction

Clerk

A cron-like scheduler with sane DSL

Example usage

Job MACRO

(job "Say 'Hi' all the time" every 5.seconds (print "Hi"))

(job "Compose and send monthly report"
     every 1.month (send-report (compose-monthly-report)))

If you want to see it with your own eyes, make sure to load the following code:

(defun write-to-file (msg file)
  (with-open-file (log file
                       :direction :output
                       :if-exists :append
                       :if-does-not-exist :create)
    (format log "~A~%" msg)))

(job "Print farbe" every 3.seconds (write-to-file "Farbe" "log.txt"))
(job "Print colour" every 2.seconds (write-to-file "Colour" "log.txt"))
(job "Print @@@@ 1 min @@@@@" every 1.minute
       (write-to-file "@@@@@@ 1 min @@@@@@" "log.txt"))

Now, after (clerk:start), tailing log.txt should give you something like this:

Colour
Farbe
Colour
Colour
Farbe
Colour
Farbe
Colour
Colour
Farbe
Colour
/one minute later.../
@@@@@@ 1 min @@@@@@
/etc.../

Job FUNCTION

The original idea was for users to use the library to execute some sort of execution of a configuration file. However you can use the job creation process programatically with the underlying function job-function. E.g.:

(defparameter *query-interval* 5)
(job-function
  #'query-api-fn
  :name (format nil "Query the API every ~A seconds" *query-interval*)
  :every `(,*query-interval* seconds))

As you can see, you have to provide a function (either anonymous function or a function symbol) as the last argument.

Installation and usage

Clerk is available in quicklisp: run (ql:quicklisp 'clerk) in your REPL to install.

Make sure your jobs are loaded before executing (clerk:start). The jobs reside inside clerk:*jobs*, but you can also type (clerk:calendar) to see a list of all scheduled and running jobs.

Job types

There are two types of jobs - continuous and one-time. If a job has the keyword every after the job description - the job will be continuous. This means that when an event is fired, a new event will be pushed in the event queue for firing exactly interval time from now. The jobs above are an example of continuous jobs.

A one-time job is fired once and then it is removed from the jobs queue. An example of a one-time job can be:

(job "Extraordinary event" in 5.days (send-mail "Don't forget X"))

Sometimes with a continuous job you want an initial delay that is different than the repetition interval:

(job "Do it lots, after a while" after 3.days every 2.seconds (send-marketing-email))

after can be used interchangeably with in.

Intervals

Right now (more are coming soon) there are 2 type of intervals:

  1. Numbered intervals
[number].[interval-type]

where the number is a positive integer and the interval-type if one of the following: second, minute, hour, day, week, month, year. Also you can use the plural form of all these words. For example 1.second and 2.seconds are both valid.

  1. Days of the week
(job "Weekly report" every monday (create-report))

Pretty self-explanatory. The idea is that if you type the day of the week, clerk will calculate when it is and add an event to the queue.

Maintenance

Clerk was written by Petko Tsikov

It is currently maintained by Ben McGunigle (bnmcgn at gmail dot com) and the team at lisp-maintainers.


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 clerk

Author

Petko Tsikov <tsikov@gmail.com>

License

MIT

Description

A cron-like scheduler with sane DSL

Version

0.1.0

Dependencies
Source

clerk.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 clerk/src

Parent

clerk (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 clerk.asd

Location

clerk.asd

Systems

clerk (system)

Packages

clerk-asd


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

4.1.2 clerk/src/time.lisp

Parent

src (module)

Location

src/time.lisp

Packages

clerk.time

Exported Definitions

timejump (function)

Internal Definitions

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

4.1.3 clerk/src/clerk.lisp

Parent

src (module)

Location

src/clerk.lisp

Packages

clerk

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 clerk-asd

Source

clerk.asd

Use List

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

5.2 clerk.time

Source

time.lisp (file)

Use List

common-lisp

Exported Definitions

timejump (function)

Internal Definitions

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

5.3 clerk

Source

clerk.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *jobs*

All scheduled jobs

Package

clerk

Source

clerk.lisp (file)


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

6.1.2 Macros

Macro: job NAME &rest TYPE/INTERVAL-PAIRS-AND-BODY
Package

clerk

Source

clerk.lisp (file)


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

6.1.3 Functions

Function: calendar &optional STREAM

Print the scheduled jobs

Package

clerk

Source

clerk.lisp (file)

Function: empty-jobs-queue ()
Package

clerk

Source

clerk.lisp (file)

Function: job-fn NAME TYPE INTERVAL FN
Package

clerk

Source

clerk.lisp (file)

Function: job-function FUNC &key NAME IN EVERY AFTER
Package

clerk

Source

clerk.lisp (file)

Function: start ()

Start the thread that waits for a jobs to fire.

Package

clerk

Source

clerk.lisp (file)

Function: stop ()

Stop scheduler

Package

clerk

Source

clerk.lisp (file)

Function: timejump START-TIME INTERVAL
Package

clerk.time

Source

time.lisp (file)


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

6.1.4 Classes

Class: job ()
Package

clerk

Source

clerk.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

name (generic function)

Slot: delay
Initargs

:delay

Readers

delay (generic function)

Slot: fire-time
Initargs

:fire-time

Readers

fire-time (generic function)

Writers

(setf fire-time) (generic function)

Slot: payload
Initargs

:payload

Readers

payload (generic function)


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

6.2 Internal definitions


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

6.2.1 Special variables

Special Variable: *days-of-the-week*
Package

clerk.time

Source

time.lisp (file)

Special Variable: *main-thread*
Package

clerk

Source

clerk.lisp (file)


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

6.2.2 Functions

Function: add-to-jobs-queue JOB
Package

clerk

Source

clerk.lisp (file)

Function: current-day-of-the-week ()

Returns the current day of the week as an integer. Monday is 0.

Package

clerk.time

Source

time.lisp (file)

Function: day-as-number DAY-AS-SYMBOL
Package

clerk.time

Source

time.lisp (file)

Function: day-of-the-week-p INTERVAL
Package

clerk.time

Source

time.lisp (file)

Function: days-to-add CURRENT TARGET

Calculates how far are the current day of the week to the target day of the week.

Package

clerk.time

Source

time.lisp (file)

Function: fire-job-if-needed ()
Package

clerk

Source

clerk.lisp (file)

Function: fire-job-p JOB

Check if it is time to fire a job

Package

clerk

Source

clerk.lisp (file)

Function: interval->seconds INTERVAL
Package

clerk.time

Source

time.lisp (file)

Function: interval-as-list INTERVAL
Package

clerk.time

Source

time.lisp (file)

Function: interval-as-list-p INTERVAL

Check if an interval is given as a list

Package

clerk.time

Source

time.lisp (file)

Function: interval-type->seconds INTERVAL-TYPE
Package

clerk.time

Source

time.lisp (file)

Function: process-pairs PAIRS
Package

clerk

Source

clerk.lisp (file)

Function: seconds-to-day-of-the-week DAY-OF-THE-WEEK

Returns the seconds to the day of the week

Package

clerk.time

Source

time.lisp (file)

Function: seconds-to-end-of-the-day CURRENT
Package

clerk.time

Source

time.lisp (file)

Function: split-interval INTERVAL
Package

clerk.time

Source

time.lisp (file)


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

6.2.3 Generic functions

Generic Function: delay OBJECT
Package

clerk

Methods
Method: delay (JOB job)

automatically generated reader method

Source

clerk.lisp (file)

Generic Function: fire-job JOB
Package

clerk

Methods
Method: fire-job (JOB continuous-job) before

Create the next job in the job queue when firing continuous jobs.

Source

clerk.lisp (file)

Method: fire-job (JOB job)
Source

clerk.lisp (file)

Generic Function: fire-time OBJECT
Generic Function: (setf fire-time) NEW-VALUE OBJECT
Package

clerk

Methods
Method: fire-time (JOB job)

automatically generated reader method

Source

clerk.lisp (file)

Method: (setf fire-time) NEW-VALUE (JOB job)

automatically generated writer method

Source

clerk.lisp (file)

Generic Function: interval OBJECT
Package

clerk

Methods
Method: interval (CONTINUOUS-JOB continuous-job)

automatically generated reader method

Source

clerk.lisp (file)

Generic Function: name OBJECT
Package

clerk

Methods
Method: name (JOB job)

automatically generated reader method

Source

clerk.lisp (file)

Generic Function: payload OBJECT
Package

clerk

Methods
Method: payload (JOB job)

automatically generated reader method

Source

clerk.lisp (file)

Generic Function: print-job JOB STREAM
Package

clerk

Source

clerk.lisp (file)

Methods
Method: print-job (JOB continuous-job) STREAM
Method: print-job (JOB job) STREAM

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

6.2.4 Classes

Class: continuous-job ()
Package

clerk

Source

clerk.lisp (file)

Direct superclasses

job (class)

Direct methods
Direct slots
Slot: interval
Initargs

:interval

Readers

interval (generic function)

Class: one-time-job ()
Package

clerk

Source

clerk.lisp (file)

Direct superclasses

job (class)


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
clerk.asd: The clerk․asd file
clerk/src: The clerk/src module
clerk/src/clerk.lisp: The clerk/src/clerk․lisp file
clerk/src/time.lisp: The clerk/src/time․lisp file

F
File, Lisp, clerk.asd: The clerk․asd file
File, Lisp, clerk/src/clerk.lisp: The clerk/src/clerk․lisp file
File, Lisp, clerk/src/time.lisp: The clerk/src/time․lisp file

L
Lisp File, clerk.asd: The clerk․asd file
Lisp File, clerk/src/clerk.lisp: The clerk/src/clerk․lisp file
Lisp File, clerk/src/time.lisp: The clerk/src/time․lisp file

M
Module, clerk/src: The clerk/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   I   J   M   N   P   S   T  
Index Entry  Section

(
(setf fire-time): Internal generic functions
(setf fire-time): Internal generic functions

A
add-to-jobs-queue: Internal functions

C
calendar: Exported functions
current-day-of-the-week: Internal functions

D
day-as-number: Internal functions
day-of-the-week-p: Internal functions
days-to-add: Internal functions
delay: Internal generic functions
delay: Internal generic functions

E
empty-jobs-queue: Exported functions

F
fire-job: Internal generic functions
fire-job: Internal generic functions
fire-job: Internal generic functions
fire-job-if-needed: Internal functions
fire-job-p: Internal functions
fire-time: Internal generic functions
fire-time: Internal generic functions
Function, add-to-jobs-queue: Internal functions
Function, calendar: Exported functions
Function, current-day-of-the-week: Internal functions
Function, day-as-number: Internal functions
Function, day-of-the-week-p: Internal functions
Function, days-to-add: Internal functions
Function, empty-jobs-queue: Exported functions
Function, fire-job-if-needed: Internal functions
Function, fire-job-p: Internal functions
Function, interval->seconds: Internal functions
Function, interval-as-list: Internal functions
Function, interval-as-list-p: Internal functions
Function, interval-type->seconds: Internal functions
Function, job-fn: Exported functions
Function, job-function: Exported functions
Function, process-pairs: Internal functions
Function, seconds-to-day-of-the-week: Internal functions
Function, seconds-to-end-of-the-day: Internal functions
Function, split-interval: Internal functions
Function, start: Exported functions
Function, stop: Exported functions
Function, timejump: Exported functions

G
Generic Function, (setf fire-time): Internal generic functions
Generic Function, delay: Internal generic functions
Generic Function, fire-job: Internal generic functions
Generic Function, fire-time: Internal generic functions
Generic Function, interval: Internal generic functions
Generic Function, name: Internal generic functions
Generic Function, payload: Internal generic functions
Generic Function, print-job: Internal generic functions

I
interval: Internal generic functions
interval: Internal generic functions
interval->seconds: Internal functions
interval-as-list: Internal functions
interval-as-list-p: Internal functions
interval-type->seconds: Internal functions

J
job: Exported macros
job-fn: Exported functions
job-function: Exported functions

M
Macro, job: Exported macros
Method, (setf fire-time): Internal generic functions
Method, delay: Internal generic functions
Method, fire-job: Internal generic functions
Method, fire-job: Internal generic functions
Method, fire-time: Internal generic functions
Method, interval: Internal generic functions
Method, name: Internal generic functions
Method, payload: Internal generic functions
Method, print-job: Internal generic functions
Method, print-job: Internal generic functions

N
name: Internal generic functions
name: Internal generic functions

P
payload: Internal generic functions
payload: Internal generic functions
print-job: Internal generic functions
print-job: Internal generic functions
print-job: Internal generic functions
process-pairs: Internal functions

S
seconds-to-day-of-the-week: Internal functions
seconds-to-end-of-the-day: Internal functions
split-interval: Internal functions
start: Exported functions
stop: Exported functions

T
timejump: Exported functions

Jump to:   (  
A   C   D   E   F   G   I   J   M   N   P   S   T  

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

A.3 Variables

Jump to:   *  
D   F   I   N   P   S  
Index Entry  Section

*
*days-of-the-week*: Internal special variables
*jobs*: Exported special variables
*main-thread*: Internal special variables

D
delay: Exported classes

F
fire-time: Exported classes

I
interval: Internal classes

N
name: Exported classes

P
payload: Exported classes

S
Slot, delay: Exported classes
Slot, fire-time: Exported classes
Slot, interval: Internal classes
Slot, name: Exported classes
Slot, payload: Exported classes
Special Variable, *days-of-the-week*: Internal special variables
Special Variable, *jobs*: Exported special variables
Special Variable, *main-thread*: Internal special variables

Jump to:   *  
D   F   I   N   P   S  

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

A.4 Data types

Jump to:   C   J   O   P   S  
Index Entry  Section

C
Class, continuous-job: Internal classes
Class, job: Exported classes
Class, one-time-job: Internal classes
clerk: The clerk system
clerk: The clerk package
clerk-asd: The clerk-asd package
clerk.time: The clerk․time package
continuous-job: Internal classes

J
job: Exported classes

O
one-time-job: Internal classes

P
Package, clerk: The clerk package
Package, clerk-asd: The clerk-asd package
Package, clerk.time: The clerk․time package

S
System, clerk: The clerk system

Jump to:   C   J   O   P   S