JBoss.orgCommunity Documentation

Chapter 7. Immutant Jobs

7.1. Introduction

Jobs in Immutant are simply functions that execute on a recurring schedule. They fire asynchronously, outside of the thread where they are defined, and fire in the same runtime as the rest of the application, so have access to any shared state.

Jobs are built on top of the Quartz library, and support scheduling via a cron-like specification.

7.2. Scheduling Jobs

Scheduling a job is as simple as calling immutant.jobs/schedule:

(ns my.ns
  (:require [immutant.jobs :as jobs]))

(jobs/schedule "my-job-name" "*/5 * * * * ?" 
               #(println "I was called!")
               :singleton false)

The schedule function requires three arguments, and also accepts options:

  • name - the name of the job. If the given name is the same as the name of previously scheduled job in the application's runtime, the prior job will be unscheduled and the new job will be scheduled in its place.
  • spec - the cron-style specification string. See Cron Syntax.
  • f - the zero argument function that will be invoked each time the job fires.
  • options - options are specified as alternating key & value literals. Valid options are:
    OptionDefaultDescription
    :singletontrueMarks the job as a singleton in a cluster. Singleton jobs will only execute on one node. If false, the job will execute on every node.

Job scheduling is dynamic, and can occur anywhere in your application code. Jobs that share the lifecycle of your application are idiomatically placed in immutant.clj.

You can safely call schedule multiple times with the same job name - the named job will rescheduled.

7.2.1. Cron Syntax

The spec attribute should contain a crontab-like entry. This is similar to cron specifications used by Vixie cron, anacron and friends, but includes an additional field for specifying seconds. It is composed of 7 fields (6 are required):

SecondsMinutesHoursDay of MonthMonthDay of WeekYear
0-590-590-231-311-12 or JAN-DEC1-7 or SUN-SAT1970-2099 (optional)

For several fields, you may denote subdivision by using the forward-slash (/) character. To execute a job every 5 minutes, */5 in the minutes field would specify this condition.

Spans may be indicated using the dash (-) character. To execute a job Monday through Friday, MON-FRI should be used in the day-of-week field.

Multiple values may be separated using the comma (,) character. The specification of 1,15 in the day-of-month field would result in the job firing on the 1st and 15th of each month.

Either day-of-month or day-of-week must be specified using the ? character, since specifying both is contradictory.

See the Quartz cron specification for additional details.

7.3. Unscheduling Jobs

Jobs can be unscheduled via the immutant.jobs/unschedule function:

(require '[immutant.jobs :as jobs])

(jobs/unschedule "my-job-name")

The unschedule function requires one argument:

  • name - the name of a previously scheduled job.

If the given name resolves to an existing job, that job will be unscheduled and the call will return true, otherwise nil is returned.

Jobs are automatically unscheduled when your application is undeployed.

Immutant 0.1.0