Client API to beanstalkd work queue.
- connectBeanstalk :: HostName -> String -> IO BeanstalkServer
- disconnectBeanstalk :: BeanstalkServer -> IO ()
- putJob :: BeanstalkServer -> Int -> Int -> Int -> String -> IO (JobState, Int)
- releaseJob :: BeanstalkServer -> Int -> Int -> Int -> IO ()
- reserveJob :: BeanstalkServer -> IO Job
- reserveJobWithTimeout :: BeanstalkServer -> Int -> IO Job
- deleteJob :: BeanstalkServer -> Int -> IO ()
- buryJob :: BeanstalkServer -> Int -> Int -> IO ()
- peekJob :: BeanstalkServer -> Int -> IO Job
- peekReadyJob :: BeanstalkServer -> IO Job
- peekDelayedJob :: BeanstalkServer -> IO Job
- peekBuriedJob :: BeanstalkServer -> IO Job
- kickJobs :: BeanstalkServer -> Int -> IO Int
- touchJob :: BeanstalkServer -> Int -> IO ()
- useTube :: BeanstalkServer -> String -> IO ()
- watchTube :: BeanstalkServer -> String -> IO Int
- ignoreTube :: BeanstalkServer -> String -> IO Int
- pauseTube :: BeanstalkServer -> String -> Int -> IO ()
- listTubes :: BeanstalkServer -> IO [String]
- listTubesWatched :: BeanstalkServer -> IO [String]
- listTubeUsed :: BeanstalkServer -> IO String
- statsJob :: BeanstalkServer -> Int -> IO (Map String String)
- statsTube :: BeanstalkServer -> String -> IO (Map String String)
- statsServer :: BeanstalkServer -> IO (Map String String)
- jobCountWithState :: BeanstalkServer -> String -> [JobState] -> IO Int
- printStats :: Map String String -> IO ()
- printList :: [String] -> IO ()
- isNotFoundException :: BeanstalkException -> Bool
- isBadFormatException :: BeanstalkException -> Bool
- isTimedOutException :: BeanstalkException -> Bool
- isOutOfMemoryException :: BeanstalkException -> Bool
- isInternalErrorException :: BeanstalkException -> Bool
- isJobTooBigException :: BeanstalkException -> Bool
- isDeadlineSoonException :: BeanstalkException -> Bool
- isNotIgnoredException :: BeanstalkException -> Bool
- data Job = Job {}
- type BeanstalkServer = MVar Socket
- data JobState
- data BeanstalkException
Connecting and Disconnecting
:: HostName | Hostname of beanstalkd server |
-> String | Port number of server |
-> IO BeanstalkServer | Server object for commands to operate on |
Connect to a beanstalkd server.
:: BeanstalkServer | Beanstalk server |
-> IO () |
Disconnect from a beanstalkd server. Any jobs reserved from this connection will be released
Beanstalk Job Commands
:: BeanstalkServer | Beanstalk server |
-> Int | Job priority: an integer less than 2**32. Jobs with smaller priorities are scheduled before jobs with larger priorities. The most urgent priority is 0; the least urgent priority is 4294967295. |
-> Int | Number of seconds to delay putting the job into the
ready queue. Until that time expires, the job will
have a state of |
-> Int | Maximum time-to-run in seconds for a reserved job.
This timer starts when a job is reserved. If it
expires without a |
-> String | Job body. |
-> IO (JobState, Int) | State of the newly created job and its ID |
Put a new job on the current tube that was selected with useTube. Specify numeric priority, delay before becoming active, a limit on the time-to-run, and a job body. Returns job state and ID.
:: BeanstalkServer | Beanstalk server |
-> Int | ID of the job to release |
-> Int | New priority to assign the job |
-> Int | Delay before the job is placed on the ready queue |
-> IO () |
Indicate that a job should be released back to the tube for another consumer.
:: BeanstalkServer | Beanstalk server |
-> IO Job | Job reserved by this client |
Reserve a new job from the watched tube list, blocking until one
becomes available. DeadlineSoonException
may be thrown if a job
reserved by the same client is about to expire.
:: BeanstalkServer | Beanstalk server |
-> Int | Time in seconds to wait for a job
to become available. Once this time
passes, a |
-> IO Job | Job reserved by this client |
Reserve a job from the watched tube list, blocking for the specified number of seconds or until a job is returned. If no jobs are found before the timeout value, a TimedOutException will be thrown. If another reserved job is about to exceed its time-to-run, a DeadlineSoonException will be thrown.
:: BeanstalkServer | Beanstalk server |
-> Int | ID of the job to delete |
-> IO () |
Delete a job to indicate that it has been completed. If the job
does not exist, was not reserved by this client, or is not in the
READY
or BURIED
state, a NotFoundException
will be thrown.
:: BeanstalkServer | Beanstalk server |
-> Int | ID of the job to bury |
-> Int | New priority to assign the job |
-> IO () |
Bury a job so that it cannot be reserved.
:: BeanstalkServer | Beanstalk server |
-> Int | ID of job to get information about |
-> IO Job | Job definition |
Inspect a specific job in the system.
:: BeanstalkServer | Beanstalk server |
-> IO Job | Job definition |
Inspect the next ready job on the currently used tube.
:: BeanstalkServer | Beanstalk server |
-> IO Job | Job definition |
Inspect the delayed job with shortest delay remaining on the currently used tube.
:: BeanstalkServer | Beanstalk server |
-> IO Job | Job definition |
Inspect the next buried job on the currently used tube.
:: BeanstalkServer | Beanstalk server |
-> Int | Number of jobs to kick |
-> IO Int | Number of jobs actually kicked |
Move jobs from current tube into ready queue. If buried jobs exist, only those will be moved, otherwise delayed jobs will be made ready.
:: BeanstalkServer | Beanstalk server |
-> Int | ID of job |
-> IO () |
Update the Time-To-Run (TTR) value for a job, giving a worker more time before job expiry.
Beanstalk Tube Commands
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube to watch |
-> IO () |
Assign a tube for new jobs created with put command. If the tube does not already exist, it will be created. Initially, all sessions will use the tube named "default".
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube to watch |
-> IO Int | Number of tubes currently being watched |
Add a named tube to the watch list, those tubes which
reserveJob
will request jobs from.
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube to ignore |
-> IO Int | Number of tubes currently being watched |
Removes the named tube to watch list. If the tube being ignored
is the only one currently being watched, a NotIgnoredException
is thrown.
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube to pause |
-> Int | Number of seconds before reservations are accepted again |
-> IO () |
Pause a tube for a specified time, so that reservations are no longer accepted.
:: BeanstalkServer | Beanstalk server |
-> IO [String] | Names of all tubes on the server |
List all existing tubes.
:: BeanstalkServer | Beanstalk server |
-> IO [String] | Names of all currently watched tubes |
List all watched tubes.
:: BeanstalkServer | Beanstalk server |
-> IO String | Name of current used tube |
List used tube.
Beanstalk Stats Commands
:: BeanstalkServer | Beanstalk server |
-> Int | ID of job |
-> IO (Map String String) | Key-value map of job statistics |
Return statistical information about a job. Keys that can be expected to be returned are the following:
id
- ID of the job.
tube
- The tube that contains this job
state
- State of the job, either "ready", "delayed", "reserved", or "buried"
pri
- Priority of the job
age
- Time in seconds since the
putJob
command created this job time-left
- Time in seconds until this job is placed in the ready queue, if it is currently reserved or delayed
reserves
- Number of times this job has been reserved
timeouts
- Number of times this job has timed out after a reservation
releases
- Number of times this job has been released
buries
- Number of times this job has been buried
kicks
- Number of times this job has been kicked
See the Beanstalk protocol docs for the definitive list and definitions.
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube |
-> IO (Map String String) | Key-value map of tube statistics |
Return statistical information about a tube. Keys that can be expected to be returned are the following:
name
- Name of the tube
current-jobs-urgent
- Number of jobs in this tube with state
READY
, with priority less than 1024 current-jobs-ready
- Number of jobs in this tube with state
READY
current-jobs-reserved
- Number of jobs in this tube with state
RESERVED
current-jobs-delayed
- Number of jobs in this tube with state
DELAYED
current-jobs-buried
- Number of jobs in this tube with state
BURIED
total-jobs
- Number of jobs that have been created in this tube since it was created
current-waiting
- Number of clients that have issued a reserve command for this tube, and are still blocking waiting on a response
pause
- Number of seconds this tube has been paused
cmd-pause-tube
- Number of seconds this tube has been paused
pause-time-left
- Seconds remaining until this tube accepts job reservations
See the Beanstalk protocol docs for the definitive list and definitions.
:: BeanstalkServer | Beanstalk server |
-> IO (Map String String) | Key-value map of server statistics |
Return statistical information about the server, across all clients. Keys that can be expected to be returned are the following:
current-jobs-urgent
- Number of
READY
jobs with priority less than 1024 current-jobs-ready
- Number of jobs in the ready queue
current-jobs-reserved
- Number of jobs reserved
current-jobs-delayed
- Number of delayed jobs
current-jobs-buried
- Number of buried jobs
cmd-put
- Cumulative number of
putJob
commands issued cmd-peek
- Cumulative number of
peekJob
commands issued cmd-peek-ready
- Cumulative number of
peekReadyJob
commands issued cmd-peek-delayed
- Cumulative number of
peekDelayedJob
commands issued cmd-peek-buried
- Cumulative number of
peekBuriedJob
commands issued cmd-reserve
- Cumulative number of
reserveJob
commands issued cmd-use
- Cumulative number of
useTube
commands issued cmd-watch
- Cumulative number of
watchTube
commands issued cmd-ignore
- Cumulative number of
ignoreTube
commands issued cmd-delete
- Cumulative number of
deleteJob
commands issued cmd-release
- Cumulative number of
releaseJob
commands issued cmd-bury
- Cumulative number of
buryJob
commands issued cmd-kick
- Cumulative number of
kickJobs
commands issued cmd-stats
- Cumulative number of
statsServer
commands issued cmd-stats-job
- Cumulative number of
statsJob
commands issued cmd-stats-tube
- Cumulative number of
statsTube
commands issued cmd-list-tubes
- Cumulative number of
listTubes
commands issued cmd-list-tube-used
- Cumulative number of
listTubeUsed
commands issued cmd-list-tubes-watched
- Cumulative number of
listTubesWatched
commands issued cmd-pause-tube
- Cumulative number of
pauseTube
commands issued job-timeouts
- Cumulative number of times a job has timed out
total-jobs
- Total count of jobs created
max-job-size
- Maximum number of bytes for a job body
current-tubes
- Current number of existing tubes
current-connections
- Number of currently open connections
current-producers
- Number of currently open connections that
have issued at least one
putJob
command current-workers
- Number of currently open connections that
have issued at least one
reserveJob
command current-waiting
- Number of currently open connections that are
blocking on a
reserveJob
orreserveJobWithTimeout
command total-connections
- Cumulative count of connections
pid
- Process ID of the server
version
- Server's version string
rusage-utime
- The accumulated user CPU time of the server process in seconds and microseconds
rusage-stime
- The accumulated system CPU time of the server process in seconds and microseconds
uptime
- The number of seconds since the server started
binlog-oldest-index
- The index of the oldest binlog file needed to store the current jobs
binlog-current-index
- The index of the current binlog file being written to. If the binlog is not active, this is zero
binlog-max-size
- The maximum number of bytes for a binlog file before a new binlog file is opened
See the Beanstalk protocol docs for the definitive list and definitions.
:: BeanstalkServer | Beanstalk server |
-> String | Name of tube to inspect |
-> [JobState] | List of valid states for count |
-> IO Int | Number of jobs with a state in the valid list |
Count number of jobs in a tube with a state in a given list. This is not part of the beanstalk protocol spec, so multiple commands are issued to retrieve the count. Therefore, the result may not be consistent (it does not represent one snapshot in time).
Pretty-Printing Stats and Lists
:: Map String String | Key-value map of statistic names and values |
-> IO () | Screen output showing all "key => value" pairs |
Print stats to screen in a readable format.
Pretty print a list.
Exception Predicates
isNotFoundException :: BeanstalkException -> BoolSource
Predicate to detect NotFoundException
isBadFormatException :: BeanstalkException -> BoolSource
Predicate to detect BadFormatException
isTimedOutException :: BeanstalkException -> BoolSource
Predicate to detect TimedOutException
isOutOfMemoryException :: BeanstalkException -> BoolSource
Predicate to detect OutOfMemoryException
isInternalErrorException :: BeanstalkException -> BoolSource
Predicate to detect InternalErrorException
isJobTooBigException :: BeanstalkException -> BoolSource
Predicate to detect JobTooBigException
isDeadlineSoonException :: BeanstalkException -> BoolSource
Predicate to detect DeadlineSoonException
isNotIgnoredException :: BeanstalkException -> BoolSource
Predicate to detect NotIgnoredException
Data Types
Information essential to performing a job and operating on it.
type BeanstalkServer = MVar SocketSource
Beanstalk Server, wrapped in an MVar
for synchronizing access
to the server socket. As many of these can be created as are
needed, but jobs are associated to a single server session and
must be released/deleted with the same session that reserved
them.
States describing the lifecycle of a job.
data BeanstalkException Source
Exceptions generated from the beanstalkd server
NotFoundException | Job does not exist, or is not reserved by this client. |
OutOfMemoryException | The server did not have enough memory available to create the job. |
InternalErrorException | The server detected an internal error. If this happens, please report to http://groups.google.com/group/beanstalk-talk. |
DrainingException | The server is in drain mode, and is not accepting new jobs. |
BadFormatException | Client sent a command that was not understood. May indicate a bad argument list or other format violation. |
UnknownCommandException | The server did not recognize a command. Should never occur, this is either a bug in the hbeanstalk library or an incompatible server version. |
JobTooBigException | A |
ExpectedCRLFException | This library failed to terminate a job body with a CR-LF terminator. Should never occur, if it does it is a bug in hbeanstalk. |
DeadlineSoonException | Not strictly an error condition, this indicates a job this client has reserved is about to expire. See http://groups.google.com/group/beanstalk-talk/browse_thread/thread/232d0cac5bebe30f for a detailed explanation. |
TimedOutException | Timeout for |
NotIgnoredException | Client attempted to ignore the only tube in its watch list (clients must always watch one or more tubes). |