-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Client for the beanstalkd workqueue service.
--   
--   This is the hbeanstalk library. It provides a client interface to a
--   beanstalkd server, allowing Haskell to be a producer and/or a consumer
--   of work items. Let Haskell do your heavy lifting!
@package hbeanstalk
@version 0.2.4


-- | Client API to beanstalkd work queue.
module Network.Beanstalk

-- | Connect to a beanstalkd server.
connectBeanstalk :: HostName -> String -> IO BeanstalkServer

-- | Disconnect from a beanstalkd server. Any jobs reserved from this
--   connection will be released
disconnectBeanstalk :: BeanstalkServer -> IO ()

-- | 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.
putJob :: BeanstalkServer -> Int -> Int -> Int -> ByteString -> IO (JobState, Int)

-- | Indicate that a job should be released back to the tube for another
--   consumer.
releaseJob :: BeanstalkServer -> Int -> Int -> Int -> IO ()

-- | Reserve a new job from the watched tube list, blocking until one
--   becomes available. <a>DeadlineSoonException</a> may be thrown if a job
--   reserved by the same client is about to expire.
reserveJob :: BeanstalkServer -> IO Job

-- | 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 <a>TimedOutException</a> will be thrown.
--   If another reserved job is about to exceed its time-to-run, a
--   <a>DeadlineSoonException</a> will be thrown.
reserveJobWithTimeout :: BeanstalkServer -> Int -> IO Job

-- | 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
--   <a>READY</a> or <a>BURIED</a> state, a <a>NotFoundException</a> will
--   be thrown.
deleteJob :: BeanstalkServer -> Int -> IO ()

-- | Bury a job so that it cannot be reserved.
buryJob :: BeanstalkServer -> Int -> Int -> IO ()

-- | Inspect a specific job in the system.
peekJob :: BeanstalkServer -> Int -> IO Job

-- | Inspect the next ready job on the currently used tube.
peekReadyJob :: BeanstalkServer -> IO Job

-- | Inspect the delayed job with shortest delay remaining on the currently
--   used tube.
peekDelayedJob :: BeanstalkServer -> IO Job

-- | Inspect the next buried job on the currently used tube.
peekBuriedJob :: BeanstalkServer -> IO Job

-- | Move jobs from current tube into ready queue. If buried jobs exist,
--   only those will be moved, otherwise delayed jobs will be made ready.
kickJobs :: BeanstalkServer -> Int -> IO Int

-- | Update the Time-To-Run (TTR) value for a job, giving a worker more
--   time before job expiry.
touchJob :: BeanstalkServer -> Int -> 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".
useTube :: BeanstalkServer -> ByteString -> IO ()

-- | Add a named tube to the watch list, those tubes which
--   <a>reserveJob</a> will request jobs from.
watchTube :: BeanstalkServer -> ByteString -> IO Int

-- | Removes the named tube to watch list. If the tube being ignored is the
--   only one currently being watched, a <a>NotIgnoredException</a> is
--   thrown.
ignoreTube :: BeanstalkServer -> ByteString -> IO Int

-- | Pause a tube for a specified time, so that reservations are no longer
--   accepted.
pauseTube :: BeanstalkServer -> ByteString -> Int -> IO ()

-- | List all existing tubes.
listTubes :: BeanstalkServer -> IO [ByteString]

-- | List all watched tubes.
listTubesWatched :: BeanstalkServer -> IO [ByteString]

-- | List used tube.
listTubeUsed :: BeanstalkServer -> IO ByteString

-- | Return statistical information about a job. Keys that can be expected
--   to be returned are the following:
--   
--   <ul>
--   <li><i><tt>id</tt></i> ID of the job.</li>
--   <li><i><tt>tube</tt></i> The tube that contains this job</li>
--   <li><i><tt>state</tt></i> State of the job, either "ready", "delayed",
--   "reserved", or "buried"</li>
--   <li><i><tt>pri</tt></i> Priority of the job</li>
--   <li><i><tt>age</tt></i> Time in seconds since the <a>putJob</a>
--   command created this job</li>
--   <li><i><tt>time-left</tt></i> Time in seconds until this job is placed
--   in the ready queue, if it is currently reserved or delayed</li>
--   <li><i><tt>reserves</tt></i> Number of times this job has been
--   reserved</li>
--   <li><i><tt>timeouts</tt></i> Number of times this job has timed out
--   after a reservation</li>
--   <li><i><tt>releases</tt></i> Number of times this job has been
--   released</li>
--   <li><i><tt>buries</tt></i> Number of times this job has been
--   buried</li>
--   <li><i><tt>kicks</tt></i> Number of times this job has been
--   kicked</li>
--   </ul>
--   
--   See the Beanstalk protocol docs for the definitive list and
--   definitions.
statsJob :: BeanstalkServer -> Int -> IO (Map ByteString ByteString)

-- | Return statistical information about a tube. Keys that can be expected
--   to be returned are the following:
--   
--   <ul>
--   <li><i><tt>name</tt></i> Name of the tube</li>
--   <li><i><tt>current-jobs-urgent</tt></i> Number of jobs in this tube
--   with state <a>READY</a>, with priority less than 1024</li>
--   <li><i><tt>current-jobs-ready</tt></i> Number of jobs in this tube
--   with state <a>READY</a></li>
--   <li><i><tt>current-jobs-reserved</tt></i> Number of jobs in this tube
--   with state <a>RESERVED</a></li>
--   <li><i><tt>current-jobs-delayed</tt></i> Number of jobs in this tube
--   with state <a>DELAYED</a></li>
--   <li><i><tt>current-jobs-buried</tt></i> Number of jobs in this tube
--   with state <a>BURIED</a></li>
--   <li><i><tt>total-jobs</tt></i> Number of jobs that have been created
--   in this tube since it was created</li>
--   <li><i><tt>current-waiting</tt></i> Number of clients that have issued
--   a reserve command for this tube, and are still blocking waiting on a
--   response</li>
--   <li><i><tt>pause</tt></i> Number of seconds this tube has been
--   paused</li>
--   <li><i><tt>cmd-pause-tube</tt></i> Number of seconds this tube has
--   been paused</li>
--   <li><i><tt>pause-time-left</tt></i> Seconds remaining until this tube
--   accepts job reservations</li>
--   </ul>
--   
--   See the Beanstalk protocol docs for the definitive list and
--   definitions.
statsTube :: BeanstalkServer -> ByteString -> IO (Map ByteString ByteString)

-- | Return statistical information about the server, across all clients.
--   Keys that can be expected to be returned are the following:
--   
--   <ul>
--   <li><i><tt>current-jobs-urgent</tt></i> Number of <a>READY</a> jobs
--   with priority less than 1024</li>
--   <li><i><tt>current-jobs-ready</tt></i> Number of jobs in the ready
--   queue</li>
--   <li><i><tt>current-jobs-reserved</tt></i> Number of jobs reserved</li>
--   <li><i><tt>current-jobs-delayed</tt></i> Number of delayed jobs</li>
--   <li><i><tt>current-jobs-buried</tt></i> Number of buried jobs</li>
--   <li><i><tt>cmd-put</tt></i> Cumulative number of <a>putJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-peek</tt></i> Cumulative number of <a>peekJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-peek-ready</tt></i> Cumulative number of
--   <a>peekReadyJob</a> commands issued</li>
--   <li><i><tt>cmd-peek-delayed</tt></i> Cumulative number of
--   <a>peekDelayedJob</a> commands issued</li>
--   <li><i><tt>cmd-peek-buried</tt></i> Cumulative number of
--   <a>peekBuriedJob</a> commands issued</li>
--   <li><i><tt>cmd-reserve</tt></i> Cumulative number of <a>reserveJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-use</tt></i> Cumulative number of <a>useTube</a>
--   commands issued</li>
--   <li><i><tt>cmd-watch</tt></i> Cumulative number of <a>watchTube</a>
--   commands issued</li>
--   <li><i><tt>cmd-ignore</tt></i> Cumulative number of <a>ignoreTube</a>
--   commands issued</li>
--   <li><i><tt>cmd-delete</tt></i> Cumulative number of <a>deleteJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-release</tt></i> Cumulative number of <a>releaseJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-bury</tt></i> Cumulative number of <a>buryJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-kick</tt></i> Cumulative number of <a>kickJobs</a>
--   commands issued</li>
--   <li><i><tt>cmd-stats</tt></i> Cumulative number of <a>statsServer</a>
--   commands issued</li>
--   <li><i><tt>cmd-stats-job</tt></i> Cumulative number of <a>statsJob</a>
--   commands issued</li>
--   <li><i><tt>cmd-stats-tube</tt></i> Cumulative number of
--   <a>statsTube</a> commands issued</li>
--   <li><i><tt>cmd-list-tubes</tt></i> Cumulative number of
--   <a>listTubes</a> commands issued</li>
--   <li><i><tt>cmd-list-tube-used</tt></i> Cumulative number of
--   <a>listTubeUsed</a> commands issued</li>
--   <li><i><tt>cmd-list-tubes-watched</tt></i> Cumulative number of
--   <a>listTubesWatched</a> commands issued</li>
--   <li><i><tt>cmd-pause-tube</tt></i> Cumulative number of
--   <a>pauseTube</a> commands issued</li>
--   <li><i><tt>job-timeouts</tt></i> Cumulative number of times a job has
--   timed out</li>
--   <li><i><tt>total-jobs</tt></i> Total count of jobs created</li>
--   <li><i><tt>max-job-size</tt></i> Maximum number of bytes for a job
--   body</li>
--   <li><i><tt>current-tubes</tt></i> Current number of existing
--   tubes</li>
--   <li><i><tt>current-connections</tt></i> Number of currently open
--   connections</li>
--   <li><i><tt>current-producers</tt></i> Number of currently open
--   connections that have issued at least one <a>putJob</a> command</li>
--   <li><i><tt>current-workers</tt></i> Number of currently open
--   connections that have issued at least one <a>reserveJob</a>
--   command</li>
--   <li><i><tt>current-waiting</tt></i> Number of currently open
--   connections that are blocking on a <a>reserveJob</a> or
--   <a>reserveJobWithTimeout</a> command</li>
--   <li><i><tt>total-connections</tt></i> Cumulative count of
--   connections</li>
--   <li><i><tt>pid</tt></i> Process ID of the server</li>
--   <li><i><tt>version</tt></i> Server's version string</li>
--   <li><i><tt>rusage-utime</tt></i> The accumulated user CPU time of the
--   server process in seconds and microseconds</li>
--   <li><i><tt>rusage-stime</tt></i> The accumulated system CPU time of
--   the server process in seconds and microseconds</li>
--   <li><i><tt>uptime</tt></i> The number of seconds since the server
--   started</li>
--   <li><i><tt>binlog-oldest-index</tt></i> The index of the oldest binlog
--   file needed to store the current jobs</li>
--   <li><i><tt>binlog-current-index</tt></i> The index of the current
--   binlog file being written to. If the binlog is not active, this is
--   zero</li>
--   <li><i><tt>binlog-max-size</tt></i> The maximum number of bytes for a
--   binlog file before a new binlog file is opened</li>
--   </ul>
--   
--   See the Beanstalk protocol docs for the definitive list and
--   definitions.
statsServer :: BeanstalkServer -> IO (Map ByteString ByteString)

-- | 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).
jobCountWithState :: BeanstalkServer -> ByteString -> [JobState] -> IO Int

-- | Print stats to screen in a readable format.
printStats :: Map ByteString ByteString -> IO ()

-- | Pretty print a list.
printList :: [ByteString] -> IO ()

-- | Predicate to detect <a>NotFoundException</a>
isNotFoundException :: BeanstalkException -> Bool

-- | Predicate to detect <a>BadFormatException</a>
isBadFormatException :: BeanstalkException -> Bool

-- | Predicate to detect <a>TimedOutException</a>
isTimedOutException :: BeanstalkException -> Bool

-- | Predicate to detect <a>OutOfMemoryException</a>
isOutOfMemoryException :: BeanstalkException -> Bool

-- | Predicate to detect <a>InternalErrorException</a>
isInternalErrorException :: BeanstalkException -> Bool

-- | Predicate to detect <a>JobTooBigException</a>
isJobTooBigException :: BeanstalkException -> Bool

-- | Predicate to detect <a>DeadlineSoonException</a>
isDeadlineSoonException :: BeanstalkException -> Bool

-- | Predicate to detect <a>NotIgnoredException</a>
isNotIgnoredException :: BeanstalkException -> Bool

-- | Predicate to detect <a>DrainingException</a>
isDrainingException :: BeanstalkException -> Bool

-- | Information essential to performing a job and operating on it.
data Job
Job :: Int -> ByteString -> Job

-- | Job numeric identifier
[job_id] :: Job -> Int

-- | Job body
[job_body] :: Job -> ByteString

-- | Beanstalk Server, wrapped in an <a>MVar</a> 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.
type BeanstalkServer = MVar Socket

-- | States describing the lifecycle of a job.
data JobState

-- | Ready, retrievable with <a>reserveJob</a>
READY :: JobState

-- | Reserved by a worker
RESERVED :: JobState

-- | Delayed, waiting to be put in ready queue
DELAYED :: JobState

-- | Buried, can be resurrected with <a>kickJobs</a>
BURIED :: JobState

-- | Exceptions generated from the beanstalkd server
data BeanstalkException

-- | Job does not exist, or is not reserved by this client.
NotFoundException :: BeanstalkException

-- | The server did not have enough memory available to create the job.
OutOfMemoryException :: BeanstalkException

-- | The server detected an internal error. If this happens, please report
--   to <a>http://groups.google.com/group/beanstalk-talk</a>.
InternalErrorException :: BeanstalkException

-- | The server is in drain mode, and is not accepting new jobs.
DrainingException :: BeanstalkException

-- | Client sent a command that was not understood. May indicate a bad
--   argument list or other format violation.
BadFormatException :: BeanstalkException

-- | The server did not recognize a command. Should never occur, this is
--   either a bug in the hbeanstalk library or an incompatible server
--   version.
UnknownCommandException :: BeanstalkException

-- | A <a>putJob</a> call included a body larger than the server's
--   <tt>max-job-size</tt> setting allows.
JobTooBigException :: BeanstalkException

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

-- | Not strictly an error condition, this indicates a job this client has
--   reserved is about to expire. See
--   <a>http://groups.google.com/group/beanstalk-talk/browse_thread/thread/232d0cac5bebe30f</a>
--   for a detailed explanation.
DeadlineSoonException :: BeanstalkException

-- | Timeout for <tt>reserveJobWithTimeout</tt> expired before a job became
--   available.
TimedOutException :: BeanstalkException

-- | Client attempted to ignore the only tube in its watch list (clients
--   must always watch one or more tubes).
NotIgnoredException :: BeanstalkException
instance GHC.Classes.Eq Network.Beanstalk.BeanstalkException
instance GHC.Show.Show Network.Beanstalk.BeanstalkException
instance GHC.Classes.Eq Network.Beanstalk.JobState
instance GHC.Read.Read Network.Beanstalk.JobState
instance GHC.Show.Show Network.Beanstalk.JobState
instance GHC.Classes.Eq Network.Beanstalk.Job
instance GHC.Read.Read Network.Beanstalk.Job
instance GHC.Show.Show Network.Beanstalk.Job
instance GHC.Exception.Type.Exception Network.Beanstalk.BeanstalkException
