chime.schedule — jimpil/chime 1.0.13

Lightweight scheduling library.

append-absolute! clj

(append-absolute! sched & times)

Assuming a mutable schedule which has not finished, appends the specified <times> to it. These should be after the last one already in.

append-relative-to-last! clj

(append-relative-to-last! sched offset-fn)

Assuming a mutable schedule which has not finished, appends the result of (offset-fn last-chime) into it.

chime-at clj

(chime-at times f)

(chime-at times
          f
          {:keys [error-handler on-finished on-aborted thread-factory clock
                  drop-overruns? mutable?]
           :or {error-handler default-error-handler
                thread-factory default-thread-factory
                clock times/*clock*
                mutable? false}})

Calls <f> with the current time, at every time in the <times> sequence.

(:require [chime.schedule :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)))

If one of those times is in the past (e.g. by accident), or a job spills over to the next time (i.e. overunning), it will (by default) be scheduled with no delay (i.e. 'push-forward' semantics). If you don't want that to happen, use the <drop-overruns?> option (i.e. 'catch-up' semantics).

Providing a custom <thread-factory> is supported, but optional (see default-thread-factory). Providing a custom <clock> is supported, but optional (see times/*clock*). Providing a custom (1-arg) error-handler is supported, but optional (see default-error-handler). Return truthy from this function to continue the schedule (the default), or falsy to shut it down.

Returns an AutoCloseable that you can .close in order to shutdown the schedule. You can also deref the return value to wait for the schedule to finish.

When the schedule is either manually closed (w/o an <on-aborted> callback) or exhausted, the <on-finished> callback will be called. If <on-aborted> has been provided it will be called instead (only on manual close).

default-error-handler clj

(default-error-handler e)

(default-error-handler id e)

finished? clj

(finished? sched)

Returns true if the entire schedule has finished, false otherwise.

interruptable clj macro

(interruptable & body)

Like interruptable*, but for arbitrary code that doesn't care about the argument passed to job-fns.

interruptable* clj

(interruptable* f)

Returns a function which wraps <f> with a Thread.isInterrupted() check. Worth considering when using shutdown-now! or skip-next!.

next-at clj

(next-at sched)

(next-at sched clock)

Returns the (future) ZonedDateTime when the next chime will occur, or nil if it has already started (with millisecond tolerance), or cancelled.

shutdown! clj

(shutdown! sched)

Gracefully closes the entire schedule (per pool.shutdown()). If the next task hasn't started yet, it will be cancelled, otherwise it will be allowed to finish.

shutdown-now! clj

(shutdown-now! sched)

Attempts a graceful shutdown (per shutdown!), but if the latest task is already happening attempts to interrupt it. Semantically equivalent to pool.shutdownNow().

skip-next! clj

(skip-next! sched)

Cancels the upcoming chime, potentially abruptly, as it may have already started. The rest of the schedule will remain unaffected, unless the interruption is handled by the error-handler (i.e. InterruptedException), and it returns falsy, or throws (the default one returns true). Returns true if already cancelled.

skip-next-n! clj

(skip-next-n! sched n)

Cancels the next <n> tasks. Returns a vector of booleans (per skip-next!)

skip-next?! clj

(skip-next?! sched)

Like skip-next!, but only if the upcoming task hasn't already started (with millisecond tolerance).

until-next clj

(until-next sched)

(until-next sched time-unit)

Returns the remaining time (in millis by default) until the next non-cancelled chime.

wait-for clj

(wait-for sched)

(wait-for sched timeout-ms timeout-val)

Blocking call for waiting until the schedule finishes, or the provided <timeout-ms> has elapsed. Useful as the last expression in with-open.