Readme — jarohen/chime 0.3.2

Dependency

Add the following to your project.clj/deps.edn file:

[jarohen/chime "0.3.2"]

{jarohen/chime {:mvn/version "0.3.2"}}

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 java.time - more on this below.)

Usage

Chime consists of one main function, chime.core/chime-at.

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

(:require [chime.core :as chime])
(:import [java.time Instant])

(let [now (Instant/now)]
  (chime/chime-at [(.plusSeconds now 2)
                   (.plusSeconds now 4)]
                  (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. If a schedule is cancelled before a job is started, the job will not run.

chime-at returns an AutoCloseable that can be closed 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!):

(let [now (Instant/now)]
  (chime/chime-at [(.plusSeconds now 2)
                   (.plusSeconds now 4)]

                  (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. This example runs every 5 minutes from now:

(:import [java.time Instant Duration])

(-> (chime/periodic-seq (Instant/now) (Duration/ofMinutes 5))
    rest) ; excludes *right now*

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:

(:import [java.time LocalTime ZonedDateTime ZoneId Period])

(chime/periodic-seq (-> (LocalTime/of 20 0 0)
                        (.adjustInto (ZonedDateTime/now (ZoneId/of "America/New_York")))
                        .toInstant)
                    (Period/ofDays period-days))

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:

(:import [java.time ZonedDateTime ZoneId Period LocalTime DayOfWeek])

;; Every Tuesday and Friday:
(->> (chime/periodic-seq (-> (.adjustInto (LocalTime/of 0 0)
                                          (ZonedDateTime/now (ZoneId/of "America/New_York")))
                             .toInstant)
                         (Period/ofDays period-days))

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

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

;; Last Monday of the month:
(->> (chime/periodic-seq ...)

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

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

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

(->> (chime/periodic-seq (-> (.adjustInto (LocalTime/of 0 0)
                                          (-> (ZonedDateTime/now (ZoneId/of "America/New_York"))
                                              (.withDayOfMonth 1)))
                             .toInstant)
                         (Period/ofDays period-days))

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

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

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

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

Error handling

You can pass an error-handler to chime-at - a function that takes the exception as an argument. Return truthy from this function to continue the schedule, falsy to cancel it. By default, Chime will log the error and continue the schedule.

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

`core.async`

If you already have Clojure’s core.async in your project, you may prefer chime.core-async/chime-ch

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

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

(let [now (Instant/now)
      chimes (chime-ch [(.plusSeconds now 2)
                        (.plusSeconds now 3)])]
  (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.core-async :refer [chime-ch]]
          [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

Dependency

The ‘Big Idea’™ behind Chime

Usage

Recurring schedules

Complex schedules

Error handling

`core.async`

Testing your integration with Chime

Bugs/thoughts/ideas/suggestions/patches etc

Contributors

License