Chime

Chime is a really lightweight Clojure scheduler.

(Despite the last modification date, Chime is still being actively used and maintained - just that there isn’t a lot of maintenance to do!)

Dependency

Add the following to your project.clj file:

[jarohen/chime "0.1.6"]

The ‘Big Idea’™ behind Chime

The main goal of Chime was to create the simplest possible scheduler. Many scheduling libraries have gone before, most attempting to either mimic cron-style syntax, or creating whole DSLs of their own. This is all well and good, until your scheduling needs cannot be (easily) expressed using these syntaxes.

When returning to the grass roots of a what a scheduler actually is, we realised that a scheduler is really just a promise to execute a function at a (possibly infinite) sequence of times. So, that is exactly what Chime is - and no more!

Chime doesn’t really mind how you generate this sequence of times - in the spirit of composability you are free to choose whatever method you like! (yes, even including other cron-style/scheduling DSLs!)

When using Chime in other projects, I have settled on a couple of patterns (mainly involving the rather excellent time functions provided by clj-time - more on this below.)

Usage

Chime consists of two main function, chime-ch and chime-at.

Here we are making use of clj-time’s time functions to generate the sequence of Joda times.

`chime-ch`

chime-ch is called with an ordered sequence of Joda times, and returns a channel that sends an event at each time in the sequence.

(:require [chime :refer [chime-ch]]
          [clj-time.core :as t]
          [clojure.core.async :as a :refer [<! go-loop]])

(let [chimes (chime-ch [(-> 2 t/secs t/from-now)
                        (-> 3 t/secs t/from-now)])]
  (a/<!! (go-loop []
           (when-let [msg (<! chimes)]
             (prn "Chiming at:" msg)
             (recur)))))

chime-ch uses an unbuffered channel, so cancelling a schedule is achieved simply by not reading from the channel.

You can also pass chime-ch a buffered channel as an optional argument. This is particularly useful if you need to specify the behaviour of the scheduler if one job overruns.

core.async has three main types of buffers: sliding, dropping and fixed. In these examples, imagining an hourly schedule, let’s say the 3pm run finishes at 5:10pm.

With a sliding-buffer (example below), the 4pm job would be cancelled, and the 5pm job started at 5:10.
With a dropping-buffer, the 4pm job would start at 5:10, but the 5pm job would be cancelled.
In the unbuffered example, above, the 4pm job would have been started at 5:10pm, and the 5pm job starting whenever that finished.

(:require [chime :refer [chime-ch]]
          [clj-time.core :as t]
          [clojure.core.async :as a :refer [<! go-loop]])

(let [chimes (chime-ch times {:ch (a/chan (a/sliding-buffer 1))})]
  (go-loop []
    (when-let [time (<! chimes)]
      ;; ...
      (recur))))

You can close! the channel returned by chime-ch to cancel the schedule.

`chime-at`

chime-at, on the other hand, is called with the sequence of times, and a callback function:

(:require [chime :refer [chime-at]]
          [clj-time.core :as t])

(chime-at [(-> 2 t/secs t/from-now)
           (-> 4 t/secs t/from-now)]
          (fn [time]
            (println "Chiming at" time)))

With chime-at, it is the caller’s responsibility to handle over-running jobs. chime-at will never execute jobs of the same scheduler in parallel or drop jobs.

chime-at returns a zero-arg function that can be called to cancel the schedule.

You can also pass an on-finished parameter to chime-at to run a callback when the schedule has finished (if it’s a finite schedule, of course!):

(chime-at [(-> 2 t/secs t/from-now) (-> 4 t/secs t/from-now)]
          
          (fn [time]
            (println "Chiming at" time))

          {:on-finished (fn []
                          (println "Schedule finished."))})

Recurring schedules

To achieve recurring schedules, we can lazily generate an infinite sequence of times using the new (as of 0.5.0) clj-time periodic-seq function. This example runs every 5 minutes from now:

(:require [clj-time.core :as t]
          [clj-time.periodic :refer [periodic-seq]])

(periodic-seq (t/now) 
              (-> 5 t/minutes))

To start a recurring schedule at a particular time, you can combine this example with some standard Clojure functions. Let’s say you want to run a function at 8pm New York time every day. To generate the sequence of times, you’ll need to seed the call to periodic-seq with the next time you want the function to run:

(:require [clj-time.core :as t])
(:import [org.joda.time DateTimeZone])

(->> (periodic-seq (.. (t/now)
                       (withZone (DateTimeZone/forID "America/New_York"))
                       (withTime 20 0 0 0))
                   (-> 1 t/days)))

Chime does drop any times that have already passed from the front of your sequence of times (on the condition that the sequence is ordered) so it doesn’t matter whether 8pm today has already passed - Chime will handle this gracefully.

Complex schedules

Because there is no scheduling DSL included with Chime, the sorts of schedules that you can achieve are not limited to the scope of the DSL.

Instead, complex schedules can be expressed with liberal use of standard Clojure sequence-manipulation functions:

(:require [clj-time.core :as t])
(:import [org.joda.time DateTimeConstants DateTimeZone])

;; Every Tuesday and Friday:
(->> (periodic-seq (.. (t/now)
                       (withZone (DateTimeZone/forID "America/New_York"))
                       (withTime 0 0 0 0))
                   (-> 1 t/days))
     (filter (comp #{DateTimeConstants/TUESDAY
                     DateTimeConstants/FRIDAY}
                   #(.getDayOfWeek %))))

;; Week-days
(->> (periodic-seq ...)
     (remove (comp #{DateTimeConstants/SATURDAY
                     DateTimeConstants/SUNDAY}
                   #(.getDayOfWeek %))))

;; Last Monday of the month:
(->> (periodic-seq (.. (t/now)
                       (withZone (DateTimeZone/forID "America/New_York"))
                       (withTime 0 0 0 0))
                   (-> 1 t/days))

     ;; Get all the Mondays                                        
     (filter (comp #{DateTimeConstants/MONDAY}
                   #(.getDayOfWeek %)))

     ;; Split into months
     ;; (Make sure you use partition-by, not group-by - 
     ;;  it's an infinite series!)
     (partition-by #(.getMonthOfYear %))

     ;; Only keep the last one in each month
     (map last))

;; 'Triple witching days': 
;; (The third Fridays in March, June, September and December)
;; (see http://en.wikipedia.org/wiki/Triple_witching_day)

;; Here we have to revert the start day to the first day of the month
;; so that when we split by month, we know which Friday is the third
;; Friday. (Any times that have already passed will be dropped, as
;; before)

(->> (periodic-seq (.. (t/now)
                       (withZone (DateTimeZone/forID "America/New_York"))
                       (withTime 0 0 0 0)
                       (withDayOfMonth 1)
                       (-> 1 t/days))

                   (filter (comp #{DateTimeConstants/FRIDAY}
                                 #(.getDayOfWeek %)))

                   (filter (comp #{3 6 9 12}
                                 #(.getMonthOfYear %)))

                   ;; Split into months
                   (partition-by #(.getMonthOfYear %))

                   ;; Only keep the third one in each month
                   (map #(nth % 2))))

This is quite a different approach to other scheduling libraries, and therefore I would be very interested to hear your thoughts!

Error handling

As of 0.1.1, you can pass an error-handler to chime-at - a function that takes the exception as an argument. You can either re-throw it, to prevent future occurrences of the scheduled task; or squash it to try again at the next scheduled time.

By default, Chime will print the stack trace on \*err\*, and continue the schedule.

(chime-at [times...]
          do-task-fn
          {:error-handler (fn [e] 
                            ;; log, alert, notify etc?
                            )})

Testing your integration with Chime

Testing time-dependent applications is always more challenging than other non-time-dependent systems. Chime makes this easier by allowing you to test the sequence of times independently from the execution of the scheduled job.

(Although, don’t forget to wrap your infinite sequences with (take x ...) when debugging!)

Bugs/thoughts/ideas/suggestions/patches etc

Please feel free to submit these through Github in the usual way!

Thanks!

Changes

0.1.6

PR from Bartosz to add an on-finished callback to chime-at - thanks!

0.1.5

Bugfix from Nick Rothwell (cassiel) fixing a negative interval bug - thanks!

Also, allowing you to close the channel returned by chime-ch to cancel the schedule.

No breaking changes

0.1.4

Bugfix from Philipp Rockel (rockolo) fixing a negative interval race condition - thanks!

No breaking changes

0.1.3

Added chime-ch, returning a channel. Re-implemented chime-at in terms of chime-at.

No breaking changes

0.1.2

Bug-fix for race condition - I advise everyone on earlier 0.1.x versions to upgrade.

0.1.1

No breaking changes. Added error-handling to chime-at.

0.1.0

Initial release

License

Distributed under the Eclipse Public License, the same as Clojure.

Big thanks to Malcolm Sparks for providing the initial idea, as well as his other contributions and discussions.

ebaxt/chime

Chime

Dependency

The ‘Big Idea’™ behind Chime

Usage

chime-ch

chime-at

Recurring schedules

Complex schedules

Error handling

Testing your integration with Chime

Bugs/thoughts/ideas/suggestions/patches etc

Changes

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

License

`chime-ch`

`chime-at`