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. Please start-off by using the sensible defaults provided by the configuration helpers, and tweaking config parameters on a case-by-case basis.

This function gives you a Config with a bunch of sensible defaults already applied. It requies the bare minimum arguments that this library cannot assume on your behalf.

It makes a few important assumptions about your 'jobPayload 'JSON, which are documented in defaultJobType.

Used only by defaultLogStr now. TODO: Is this even required anymore? Should this be removed?

This makes two important assumptions. First, this assumes that jobs in your app are represented by a sum-type. For example:

data MyJob = SendWelcomeEmail Int
           | SendPasswordResetEmail Text
           | SetupSampleData Int

Second, it assumes that the JSON representatin of this sum-type is "tagged". For example, the following...

let pload = SendWelcomeEmail 10

...when converted to JSON, would look like...

{"tag":"SendWelcomeEmail", "contents":10}

It uses this assumption to extract the "job type" from a Value (which would be SendWelcomeEmail in the example given above). This is used in logging and the admin UI.

Even if tihs assumption is violated, the job-runner should continue to function. It's just that you won't get very useful log messages.

TODO: Should the library be doing this?

As the name says. Ref: cfgPollingInterval

TODO: Make this configurable for the job-runner, why is this still hard-coded?

Convenience function to create a DB connection-pool with some sensible defaults. Please see the source-code of this function to understand what it's doing. TODO: link-off to tutorial.

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.

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