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


-- | Build a pool of queue-processing worker threads.
--   
--   <tt>immortal-queue</tt> is a library for build an asynchronous worker
--   pool that processes action from a generic queue. You can use any
--   thread-safe datatype with a push and pop like a <tt>TQueue</tt> or a
--   <tt>persistent</tt> database table.
--   
--   The worker pool is configured by building an <tt>ImmortalQueue</tt>
--   type, which describes how to push and pop from the queue as well as
--   how to process items and handle errors.
--   
--   For a simple usage example using a TQueue, see the module
--   documentation. For a more complex example that uses a
--   <tt>persistent</tt> database as a queue, see <a>Southern Exposure's
--   website code</a>.
@package immortal-queue
@version 0.1.0.1


-- | This module uses the <a>immortal</a> library to build a pool of worker
--   threads that process a queue of tasks asynchronously.
--   
--   First build an <a>ImmortalQueue</a> for your task type and queue
--   backend. Then you can launch the pool using
--   <a>processImmortalQueue</a> and stop the pool with
--   <a>closeImmortalQueue</a>.
--   
--   <pre>
--   import Control.Concurrent.STM (atomically)
--   import Control.Concurrent.STM.TQueue
--   import Control.Exception (Exception)
--   import Control.Immortal.Queue
--   
--   data Task
--       = Print String
--       deriving (Show)
--   
--   queueConfig :: TQueue Task -&gt; ImmortalQueue Task
--   queueConfig queue =
--       ImmortalQueue
--           { qThreadCount = 2
--           , qPollWorkerTime = 1000
--           , qPop = atomically $ readTQueue queue
--           , qPush = atomically . writeTQueue queue
--           , qHandler = performTask
--           , qFailure = printError
--           }
--     where
--       performTask :: Task -&gt; IO ()
--       performTask t = case t of
--           Print str -&gt;
--               putStrLn str
--       printError :: Exception e =&gt; Task -&gt; e -&gt; IO ()
--       printError t err =
--           let description = case t of
--                   Print str -&gt;
--                       "print"
--           in  putStrLn $ "Task `" ++ description ++ "` failed with: " ++ show err
--   
--   main :: IO ()
--   main = do
--       queue &lt;- newTQueueIO
--       workers &lt;- processImmortalQueue $ queueConfig queue
--       atomically $ mapM_ (writeTQueue queue . Print) ["hello", "world"]
--       closeImmortalQueue workers
--   </pre>
module Control.Immortal.Queue

-- | The configuration data required for initializing a worker pool.
data ImmortalQueue a
ImmortalQueue :: Natural -> Int -> IO a -> (a -> IO ()) -> (a -> IO ()) -> (forall e. Exception e => a -> e -> IO ()) -> ImmortalQueue a

-- | Number of worker threads to run.
[qThreadCount] :: ImmortalQueue a -> Natural

-- | Wait time in milliseconds for polling for a free worker.
[qPollWorkerTime] :: ImmortalQueue a -> Int

-- | A blocking action to pop the next item off of the queue.
[qPop] :: ImmortalQueue a -> IO a

-- | An action to enqueue a task. Used during shutdown if we've popped an
--   item but haven't assigned it to a worker yet.
[qPush] :: ImmortalQueue a -> a -> IO ()

-- | The handler to perform a queued task.
[qHandler] :: ImmortalQueue a -> a -> IO ()

-- | An error handler for when a thread encounters an unhandled exception.
[qFailure] :: ImmortalQueue a -> forall e. Exception e => a -> e -> IO ()

-- | Start a management thread that creates the queue-processing worker
--   threads &amp; return a QueueId that can be used to stop the workers.
processImmortalQueue :: forall a. ImmortalQueue a -> IO QueueId

-- | An identifier created by a queue manager that can be used to stop the
--   worker processes.
data QueueId

-- | Cleanly close the worker pool, allowing them to complete their
--   actions.
closeImmortalQueue :: QueueId -> IO ()

-- | Uncleanly close the worker pool, aborting current actions.
killImmortalQueue :: QueueId -> IO ()