Start the job-runner in the current thread, i.e. you'll need to use forkIO or async manually, if you want the job-runner to run in the background. Consider using Cli to rapidly build your own standalone daemon.

While odd-jobs is highly configurable and the Config data-type might seem daunting at first, it is not necessary to tweak every single configuration parameter by hand.

Recommendation: Please start-off by building a Config by using the mkConfig function (to get something with sensible defaults) and then tweaking config parameters on a case-by-case basis.

Note: Please read the section on controlling concurrency in the implementation guide to understand the implications of each option given by the data-type.

Create a job for immediate execution.

Internally calls scheduleJob passing it the current time. Read scheduleJob for further documentation.

Create a job for execution at the given time.

• If time has already past, jobEventListener is going to pick this up for execution immediately.
• If time is in the future, jobPoller is going to pick this up with an error of +/- cfgPollingInterval seconds. Please do not expect very high accuracy of when the job is actually executed.

An alias for Query type. Since this type has an instance of IsString you do not need to do anything special to create a value for this type. Just ensure you have the OverloadedStrings extention enabled. For example:

{-# LANGUAGE OverloadedStrings #-}

myJobsTable :: TableName
myJobsTable = "my_jobs"

Convenience wrapper on-top of threadDelay which takes Seconds as an argument, instead of micro-seconds.

Exception handler for jobs. This is conceptually very similar to how Handler and catches (from Exception) work in-tandem. Using cfgOnJobFailed you can install multiple exception handlers, where each handler is responsible for one type of exception. OddJobs will execute the correct exception handler on the basis of the type of runtime exception raised. For example:

cfgOnJobFailed =
  [ JobErrHandler $ (e :: HttpException) job failMode -> ...
  , JobErrHandler $ (e :: SqlException) job failMode -> ...
  , JobErrHandler $ (e :: ) job failMode -> ...
  ]

Note: Please refer to the section on alerts and notifications in the implementation guide to understand how to use the machinery provided by JobErrHandler and cfgOnJobFailed.

The web/admin UI needs to know a "master list" of all job-types to be able to power the "filter by job-type" feature. This data-type helps in letting odd-jobs know how to get such a master-list. The function specified by this type is run once when the job-runner starts (and stored in an internal IORef). After that the list of job-types needs to be updated manually by pressing the appropriate "refresh" link in the admin/web UI.

Spawns jobPoller and jobEventListener in separate threads and restarts them in the off-chance they happen to crash. Also responsible for implementing graceful shutdown, i.e. waiting for all jobs already being executed to finish execution before exiting the main thread.

Uses PostgreSQL's LISTEN/NOTIFY to be immediately notified of newly created jobs.

Executes jobPollingSql every cfgPollingInterval seconds to pick up jobs for execution. Uses UPDATE along with SELECT...FOR UPDATE to efficiently find a job that matches all of the following conditions:

• jobRunAt should be in the past

• one of the following conditions match:

  • jobStatus should be Queued or Retry
  • jobStatus should be Locked and jobLockedAt should be defaultLockTimeout seconds in the past, thus indicating that the job was picked up execution, but didn't complete on time (possible because the thread/process executing it crashed without being able to update the DB)

Ref: jobPoller

The documentation of odd-jobs currently promotes startJobRunner, which expects a fairly detailed Config record, as a top-level function for initiating a job-runner. However, internally, this Config record is used as an enviroment for a ReaderT, and almost all functions are written in this ReaderT monad which impleents an instance of the HasJobRunner type-class.

In future, this internal implementation detail will allow us to offer a type-class based interface as well (similar to what YesodJobQueue provides).

TODO: First check in all job-runners if this job is still running, or not, and somehow send an uninterruptibleCancel to that thread.

If you are writing SQL queries where you want to return ALL columns from the jobs table it is recommended that you do not issue a SELECT * or RETURNIG *. List out specific DB columns using jobDbColumns and concatJobDbColumns instead. This will insulate you from runtime errors caused by addition of new columns to cfgTableName in future versions of OddJobs.

All jobDbColumns joined together with commas. Useful for constructing SQL queries, eg:

query_ conn $ "SELECT " <> concatJobDbColumns <> "FROM jobs"

Used by the web/admin UI to fetch a "master list" of all known job-types. Ref: cfgAllJobTypes

Used by web/admin IO to fetch a "master list" of all known job-runners. There is a known issue with the way this has been implemented:

• Since this looks at the jobLockedBy column of cfgTableName, it will discover only those job-runners that are actively executing at least one job at the time this function is executed.