odd-jobs-0.1.0: A full-featured PostgreSQL-backed job queue (with an admin UI)

Safe HaskellNone
LanguageHaskell2010

OddJobs.Cli

Contents

Synopsis

Introduction

This module has a bunch of functions (that use the 'optparse-applicative' library) to help you rapidly build a standalone job-runner deamon based on odd-jobs. You should probably start-off by using the pre-packaged default behaviour, notably the defaultMain function. If the default behaviour of the resultant CLI doesn't suit your needs, consider reusing/extending the individual argument parsers. If you find you cannot reuse those, then it would be best to write your CLI from scratch instead of force-fitting whatever has been provided here.

It is highly recommended that you read the "Deployment" section in the tutorial before you put odd-jobs into production.

  • TODO: link-off to tutorial
  • TODO: link-off to simple-example

Default behaviour

defaultMain Source #

Arguments

:: ((Config -> IO ()) -> IO ())

A callback function that will be executed once the dameon has forked into the background.

-> IO () 

Please do not get scared by the type-signature of the first argument. Conceptually, it's a callback, within another callback.

The callback function that you pass to defaultMain will be executed once the job-runner has forked as a background dameon. Your callback function will be given another callback function, i.e. the Config -> IO () part that you need to call once you've setup Config and whatever environment is required to run your application code.

This complication is necessary because immediately after forking a new daemon process, a bunch of resources will need to be allocated for the job-runner to start functioning. At the minimum, a DB connection pool and logger. However, realistically, a bunch of additional resources will also be required for setting up the environment needed for running jobs in your application's monad.

All of these resource allocations need to be bracketed so that when the job-runner exits, they may be cleaned-up gracefully.

Please take a look at simple-example for how to use this function in practice. (TODO: link-off to the example).

defaultStartCommand Source #

Arguments

:: StartArgs 
-> ((Config -> IO ()) -> IO ())

the same callback-within-callback function described in defaultMain

-> IO () 

Used by defaultMain if the Start command is issued via the CLI. If --daemonize switch is also passed, it checks for startPidFile:

  • If it doesn't exist, it forks a background daemon, writes the PID file, and exits.
  • If it exists, it refuses to start, to prevent multiple invocations of the same background daemon.

defaultStopCommand :: StopArgs -> IO () Source #

Used by defaultMain if Stop command is issued via the CLI. Sends a SIGINT signal to the process indicated by shutPidFile. Waits for a maximum of shutTimeout seconds (controller by --timeout) for the daemon to shutdown gracefully, after which a SIGKILL is issued

Default CLI parsers

If the default behaviour doesn't suit your needs, you can write a main function yourself, and consider using/extending the CLI parsers documented in this section.

data Args Source #

The command-line is parsed into this data-structure using argParser

Constructors

Args 

Fields

Instances
Eq Args Source # 
Instance details

Defined in OddJobs.Cli

Methods

(==) :: Args -> Args -> Bool #

(/=) :: Args -> Args -> Bool #

Show Args Source # 
Instance details

Defined in OddJobs.Cli

Methods

showsPrec :: Int -> Args -> ShowS #

show :: Args -> String #

showList :: [Args] -> ShowS #

argParser Source #

Arguments

:: Seconds

the default value for shutTimeout

-> Parser Args 

The top-level command-line parser

Top-level command parser

data Command Source #

CLI commands are parsed into this data-structure by commandParser

Instances
Eq Command Source # 
Instance details

Defined in OddJobs.Cli

Methods

(==) :: Command -> Command -> Bool #

(/=) :: Command -> Command -> Bool #

Show Command Source # 
Instance details

Defined in OddJobs.Cli

commandParser Source #

Arguments

:: Seconds

default value for shutTimeout

-> Parser Command 

Start command

data StartArgs Source #

start command is parsed into this data-structure by startParser

Constructors

StartArgs 

Fields

Instances
Eq StartArgs Source # 
Instance details

Defined in OddJobs.Cli

Show StartArgs Source # 
Instance details

Defined in OddJobs.Cli

Stop command

data StopArgs Source #

stop command is parsed into this data-structure by stopParser. Please note, that this command first sends a SIGINT to the daemon and waits for shutTimeout seconds (which defaults to defaultLockTimeout). If the daemon doesn't shut down cleanly within that time, it sends a SIGKILL to kill immediately.

Constructors

StopArgs 

Fields

Instances
Eq StopArgs Source # 
Instance details

Defined in OddJobs.Cli

Show StopArgs Source # 
Instance details

Defined in OddJobs.Cli

Status command

statusParser :: Parser Command Source #

The status command has not been implemented yet. PRs welcome :-)

Other parsing utilities

pidFileParser :: Parser FilePath Source #

If --pid-file is not given as a command-line argument, this defaults to ./odd-jobs.pid

defaultCliInfo Source #

Arguments

:: Seconds

default value for shutTimeout

-> ParserInfo Args