The clerk Reference Manual

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 4.0 beta 2 "William Riker" on Thu Sep 15 04:22:03 2022 GMT+0.

Table of Contents


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.


2 Systems

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


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

2.1 clerk

A cron-like scheduler with sane DSL

Author

Petko Tsikov <tsikov@gmail.com>

License

MIT

Version

0.1.0

Dependencies
  • bordeaux-threads (system).
  • cl-ppcre (system).
Source

clerk.asd.

Child Component

src (module).


Next: , Previous: , Up: The clerk Reference Manual   [Contents][Index]

3 Modules

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


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

3.1 clerk/src

Source

clerk.asd.

Parent Component

clerk (system).

Child Components

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

4.1.1 clerk/clerk.asd

Source

clerk.asd.

Parent Component

clerk (system).

ASDF Systems

clerk.

Packages

clerk-asd.


4.1.2 clerk/src/time.lisp

Source

clerk.asd.

Parent Component

src (module).

Packages

clerk.time.

Public Interface

timejump (function).

Internals

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

4.1.3 clerk/src/clerk.lisp

Source

clerk.asd.

Parent Component

src (module).

Packages

clerk.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


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

5.1 clerk-asd

Source

clerk.asd.

Use List
  • asdf/interface.
  • common-lisp.

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

5.2 clerk

Source

clerk.lisp.

Use List

common-lisp.

Public Interface
Internals

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

5.3 clerk.time

Source

time.lisp.

Use List

common-lisp.

Public Interface

timejump (function).

Internals

6 Definitions

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


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

6.1 Public Interface


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

6.1.1 Special variables

Special Variable: *jobs*

All scheduled jobs

Package

clerk.

Source

clerk.lisp.


6.1.2 Macros

Macro: job (name &rest type/interval-pairs-and-body)
Package

clerk.

Source

clerk.lisp.


6.1.3 Ordinary functions

Function: calendar (&optional stream)

Print the scheduled jobs

Package

clerk.

Source

clerk.lisp.

Function: empty-jobs-queue ()
Package

clerk.

Source

clerk.lisp.

Function: job-fn (name type interval fn)
Package

clerk.

Source

clerk.lisp.

Function: job-function (func &key name in every after)
Package

clerk.

Source

clerk.lisp.

Function: start ()

Start the thread that waits for a jobs to fire.

Package

clerk.

Source

clerk.lisp.

Function: stop ()

Stop scheduler

Package

clerk.

Source

clerk.lisp.

Function: timejump (start-time interval)
Package

clerk.time.

Source

time.lisp.


6.1.4 Standalone methods

Method: initialize-instance :after ((job job) &key)
Source

clerk.lisp.


6.1.5 Classes

Class: job
Package

clerk.

Source

clerk.lisp.

Direct subclasses
Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: delay
Initargs

:delay

Readers

delay.

Writers

This slot is read-only.

Slot: fire-time
Initargs

:fire-time

Readers

fire-time.

Writers

(setf fire-time).

Slot: payload
Initargs

:payload

Readers

payload.

Writers

This slot is read-only.


6.2 Internals


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

6.2.1 Special variables

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

clerk.time.

Source

time.lisp.

Special Variable: *main-thread*
Package

clerk.

Source

clerk.lisp.


6.2.2 Ordinary functions

Function: add-to-jobs-queue (job)
Package

clerk.

Source

clerk.lisp.

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.

Function: day-as-number (day-as-symbol)
Package

clerk.time.

Source

time.lisp.

Function: day-of-the-week-p (interval)
Package

clerk.time.

Source

time.lisp.

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.

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

clerk.

Source

clerk.lisp.

Function: fire-job-p (job)

Check if it is time to fire a job

Package

clerk.

Source

clerk.lisp.

Function: interval->seconds (interval)
Package

clerk.time.

Source

time.lisp.

Function: interval-as-list (interval)
Package

clerk.time.

Source

time.lisp.

Function: interval-as-list-p (interval)

Check if an interval is given as a list

Package

clerk.time.

Source

time.lisp.

Function: interval-type->seconds (interval-type)
Package

clerk.time.

Source

time.lisp.

Function: process-pairs (pairs)
Package

clerk.

Source

clerk.lisp.

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.

Function: seconds-to-end-of-the-day (current)
Package

clerk.time.

Source

time.lisp.

Function: split-interval (interval)
Package

clerk.time.

Source

time.lisp.


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

6.2.3 Generic functions

Generic Reader: delay (object)
Package

clerk.

Methods
Reader Method: delay ((job job))

automatically generated reader method

Source

clerk.lisp.

Target Slot

delay.

Generic Function: fire-job (job)
Package

clerk.

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

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

Source

clerk.lisp.

Method: fire-job ((job job))
Source

clerk.lisp.

Generic Reader: fire-time (object)
Package

clerk.

Methods
Reader Method: fire-time ((job job))

automatically generated reader method

Source

clerk.lisp.

Target Slot

fire-time.

Generic Writer: (setf fire-time) (object)
Package

clerk.

Methods
Writer Method: (setf fire-time) ((job job))

automatically generated writer method

Source

clerk.lisp.

Target Slot

fire-time.

Generic Reader: interval (object)
Package

clerk.

Methods
Reader Method: interval ((continuous-job continuous-job))

automatically generated reader method

Source

clerk.lisp.

Target Slot

interval.

Generic Reader: name (object)
Package

clerk.

Methods
Reader Method: name ((job job))

automatically generated reader method

Source

clerk.lisp.

Target Slot

name.

Generic Reader: payload (object)
Package

clerk.

Methods
Reader Method: payload ((job job))

automatically generated reader method

Source

clerk.lisp.

Target Slot

payload.

Generic Function: print-job (job stream)
Package

clerk.

Source

clerk.lisp.

Methods
Method: print-job ((job continuous-job) stream)
Method: print-job ((job job) stream)

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

6.2.4 Classes

Class: continuous-job
Package

clerk.

Source

clerk.lisp.

Direct superclasses

job.

Direct methods
Direct slots
Slot: interval
Initargs

:interval

Readers

interval.

Writers

This slot is read-only.

Class: one-time-job
Package

clerk.

Source

clerk.lisp.

Direct superclasses

job.


Appendix A Indexes


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

A.1 Concepts


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): Private generic functions
(setf fire-time): Private generic functions

A
add-to-jobs-queue: Private ordinary functions

C
calendar: Public ordinary functions
current-day-of-the-week: Private ordinary functions

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

E
empty-jobs-queue: Public ordinary functions

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

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

I
initialize-instance: Public standalone methods
interval: Private generic functions
interval: Private generic functions
interval->seconds: Private ordinary functions
interval-as-list: Private ordinary functions
interval-as-list-p: Private ordinary functions
interval-type->seconds: Private ordinary functions

J
job: Public macros
job-fn: Public ordinary functions
job-function: Public ordinary functions

M
Macro, job: Public macros
Method, (setf fire-time): Private generic functions
Method, delay: Private generic functions
Method, fire-job: Private generic functions
Method, fire-job: Private generic functions
Method, fire-time: Private generic functions
Method, initialize-instance: Public standalone methods
Method, interval: Private generic functions
Method, name: Private generic functions
Method, payload: Private generic functions
Method, print-job: Private generic functions
Method, print-job: Private generic functions

N
name: Private generic functions
name: Private generic functions

P
payload: Private generic functions
payload: Private generic functions
print-job: Private generic functions
print-job: Private generic functions
print-job: Private generic functions
process-pairs: Private ordinary functions

S
seconds-to-day-of-the-week: Private ordinary functions
seconds-to-end-of-the-day: Private ordinary functions
split-interval: Private ordinary functions
start: Public ordinary functions
stop: Public ordinary functions

T
timejump: Public ordinary functions

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