Copyright	(c) Greg Heartsfield 2010
License	BSD3
Safe Haskell	None
Language	Haskell98

Network.Beanstalk

Contents

Connecting and Disconnecting
Beanstalk Job Commands
Beanstalk Tube Commands
Beanstalk Stats Commands
Pretty-Printing Stats and Lists
Exception Predicates
Data Types

Description

Client API to beanstalkd work queue.

Synopsis

Connecting and Disconnecting

connectBeanstalk #

Arguments

:: HostName	Hostname of beanstalkd server
-> String	Port number of server
-> IO BeanstalkServer	Server object for commands to operate on

Connect to a beanstalkd server.

disconnectBeanstalk #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO ()

Disconnect from a beanstalkd server. Any jobs reserved from this connection will be released

Beanstalk Job Commands

putJob #

Arguments

:: 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 `DELAYED`.
-> Int	Maximum time-to-run in seconds for a reserved job. This timer starts when a job is reserved. If it expires without a `deleteJob`, `releaseJob`, `buryJob`, or `touchJob` command being run, the job will be placed back on the ready queue. The minimum value is 1.
-> ByteString	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.

releaseJob #

Arguments

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

reserveJob #

Arguments

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

reserveJobWithTimeout #

Arguments

:: BeanstalkServer	Beanstalk server
-> Int	Time in seconds to wait for a job to become available. Once this time passes, a `TimedOutException` will be thrown.
-> 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.

deleteJob #

Arguments

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

buryJob #

Arguments

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

peekJob #

Arguments

:: BeanstalkServer	Beanstalk server
-> Int	ID of job to get information about
-> IO Job	Job definition

Inspect a specific job in the system.

peekReadyJob #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO Job	Job definition

Inspect the next ready job on the currently used tube.

peekDelayedJob #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO Job	Job definition

Inspect the delayed job with shortest delay remaining on the currently used tube.

peekBuriedJob #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO Job	Job definition

Inspect the next buried job on the currently used tube.

kickJobs #

Arguments

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

touchJob #

Arguments

:: 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

useTube #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	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".

watchTube #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	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.

ignoreTube #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	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.

pauseTube #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	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.

listTubes #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO [ByteString]	Names of all tubes on the server

List all existing tubes.

listTubesWatched #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO [ByteString]	Names of all currently watched tubes

List all watched tubes.

listTubeUsed #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO ByteString	Name of current used tube

List used tube.

Beanstalk Stats Commands

statsJob #

Arguments

:: BeanstalkServer	Beanstalk server
-> Int	ID of job
-> IO (Map ByteString ByteString)	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.

statsTube #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	Name of tube
-> IO (Map ByteString ByteString)	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.

statsServer #

Arguments

:: BeanstalkServer	Beanstalk server
-> IO (Map ByteString ByteString)	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 or reserveJobWithTimeout 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.

jobCountWithState #

Arguments

:: BeanstalkServer	Beanstalk server
-> ByteString	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

printStats #

Arguments

:: Map ByteString ByteString	Key-value map of statistic names and values
-> IO ()	Screen output showing all "key => value" pairs

Print stats to screen in a readable format.

printList #

Arguments

:: [ByteString]	List of names
-> IO ()	Screen output showing results with prefixed counter

Pretty print a list.

Exception Predicates

isNotFoundException :: BeanstalkException -> Bool #

Predicate to detect NotFoundException

isBadFormatException :: BeanstalkException -> Bool #

Predicate to detect BadFormatException

isTimedOutException :: BeanstalkException -> Bool #

Predicate to detect TimedOutException

isOutOfMemoryException :: BeanstalkException -> Bool #

Predicate to detect OutOfMemoryException

isInternalErrorException :: BeanstalkException -> Bool #

Predicate to detect InternalErrorException

isJobTooBigException :: BeanstalkException -> Bool #

Predicate to detect JobTooBigException

isDeadlineSoonException :: BeanstalkException -> Bool #

Predicate to detect DeadlineSoonException

isNotIgnoredException :: BeanstalkException -> Bool #

Predicate to detect NotIgnoredException

isDrainingException :: BeanstalkException -> Bool #

Predicate to detect DrainingException

Data Types

data Job #

Information essential to performing a job and operating on it.

Constructors

Job
Fields job_id :: Int Job numeric identifier job_body :: ByteString Job body

Instances

Eq Job #
Methods (==) :: Job -> Job -> Bool # (/=) :: Job -> Job -> Bool #
Read Job #
Methods readsPrec :: Int -> ReadS Job # readList :: ReadS [Job] # readPrec :: ReadPrec Job # readListPrec :: ReadPrec [Job] #
Show Job #
Methods showsPrec :: Int -> Job -> ShowS # show :: Job -> String # showList :: [Job] -> ShowS #

type BeanstalkServer = MVar Socket #

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.

data JobState #

States describing the lifecycle of a job.

Constructors

READY	Ready, retrievable with `reserveJob`
RESERVED	Reserved by a worker
DELAYED	Delayed, waiting to be put in ready queue
BURIED	Buried, can be resurrected with `kickJobs`

Instances

Eq JobState #
Methods (==) :: JobState -> JobState -> Bool # (/=) :: JobState -> JobState -> Bool #
Read JobState #
Methods readsPrec :: Int -> ReadS JobState # readList :: ReadS [JobState] # readPrec :: ReadPrec JobState # readListPrec :: ReadPrec [JobState] #
Show JobState #
Methods showsPrec :: Int -> JobState -> ShowS # show :: JobState -> String # showList :: [JobState] -> ShowS #

data BeanstalkException #

Exceptions generated from the beanstalkd server

Constructors

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 `putJob` call included a body larger than the server's `max-job-size` setting allows.
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 `reserveJobWithTimeout` expired before a job became available.
NotIgnoredException	Client attempted to ignore the only tube in its watch list (clients must always watch one or more tubes).

Instances

Eq BeanstalkException #
Methods (==) :: BeanstalkException -> BeanstalkException -> Bool # (/=) :: BeanstalkException -> BeanstalkException -> Bool #
Show BeanstalkException #
Methods showsPrec :: Int -> BeanstalkException -> ShowS # show :: BeanstalkException -> String # showList :: [BeanstalkException] -> ShowS #
Exception BeanstalkException #
Methods toException :: BeanstalkException -> SomeException # fromException :: SomeException -> Maybe BeanstalkException # displayException :: BeanstalkException -> String #