| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
OddJobs.Cli
Contents
Synopsis
- defaultMain :: ((Config -> IO ()) -> IO ()) -> IO ()
- defaultStartCommand :: StartArgs -> ((Config -> IO ()) -> IO ()) -> IO ()
- defaultStopCommand :: StopArgs -> IO ()
- data Args = Args {
- argsCommand :: !Command
- argParser :: Seconds -> Parser Args
- data Command
- commandParser :: Seconds -> Parser Command
- data StartArgs = StartArgs {
- startWebUiEnable :: !Bool
- startDaemonize :: !Bool
- startPidFile :: !FilePath
- startParser :: Parser Command
- data StopArgs = StopArgs {
- shutTimeout :: !Seconds
- shutPidFile :: !FilePath
- stopParser :: Seconds -> Parser Command
- statusParser :: Parser Command
- pidFileParser :: Parser FilePath
- defaultCliParserPrefs :: ParserPrefs
- defaultCliInfo :: Seconds -> ParserInfo Args
- defaultDaemonOptions :: DaemonOptions
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 following links before putting odd-jobs into production.
- A simple-example
of how to use the
defaultMainfunction, that should make the callback-within-callback more understandable. - TODO: link-off to "Deployment" in the tutorial
Default behaviour
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).
Arguments
| :: StartArgs | |
| -> ((Config -> IO ()) -> IO ()) | the same callback-within-callback function described in
|
| -> 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.
The command-line is parsed into this data-structure using argParser
Constructors
| Args | |
Fields
| |
Arguments
| :: Seconds | the default value for |
| -> Parser Args |
The top-level command-line parser
Top-level command parser
CLI commands are parsed into this data-structure by commandParser
Arguments
| :: Seconds | default value for |
| -> Parser Command |
Start command
start command is parsed into this data-structure by startParser
Constructors
| StartArgs | |
Fields
| |
Stop command
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
| |
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
Arguments
| :: Seconds | default value for |
| -> ParserInfo Args |