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


-- | Manage pools of possibly interdependent tasks using STM and async
--   
--   A taskpool is a network of tasks (where connection indicates
--   dependency), where up to N independent tasks at time may execute
--   concurrently.
@package taskpool
@version 0.0.1

module Data.TaskPool

-- | A <a>Pool</a> manages a collection of possibly interdependent tasks,
--   such that tasks await execution until the tasks they depend on have
--   finished (and tasks may depend on an arbitrary number of other tasks),
--   while independent tasks execute concurrently up to the number of
--   available resource slots in the pool.
--   
--   Results from each task are available until the status of the task is
--   polled or waited on. Further, the results are kept until that occurs,
--   so failing to ever wait will result in a memory leak.
--   
--   Tasks may be cancelled, in which case all dependent tasks are
--   unscheduled.
data Pool a

-- | A <a>Handle</a> is a unique reference to a task that has submitted to
--   a <a>Pool</a>.
type Handle = Node

-- | Create a thread pool for executing interdependent tasks concurrently.
--   The number of available slots governs how many tasks may run at one
--   time.
createPool :: Int -> IO (Pool a)

-- | Begin executing tasks in the given pool. The number of slots
--   determines how many threads may execute concurrently. This number is
--   adjustable dynamically, by calling <a>setPoolSlots</a>, though
--   reducing it does not cause already active threads to stop.
--   
--   Note: Setting the number of available slots to zero has the effect of
--   causing this function to exit soon after, so that <a>runPool</a> will
--   need to be called again to continue processing tasks in the
--   <a>Pool</a>.
runPool :: Pool a -> IO ()

-- | Set the number of available execution slots in the given <a>Pool</a>.
--   Increasing the number will cause waiting threads to start executing
--   immediately, while decreasing the number only decreases any available
--   slots -- it does not cancel already executing threads.
setPoolSlots :: Pool a -> Int -> STM ()

-- | Cancel every running thread in the pool and unschedule any that had
--   not begun yet.
cancelAll :: Pool a -> IO ()

-- | Submit an <a>IO</a> action for execution within the managed thread
--   pool. When it actually begins executes is determined by the number of
--   available slots, whether the threaded runtime is being used, and how
--   long it takes the jobs before it to complete.
submitTask :: Pool a -> IO a -> STM Handle

-- | Submit a task, but only allow it begin executing once its parent task
--   has completed. This is equivalent to submitting a new task and linking
--   it to its parent using <a>sequenceTasks</a> within a single STM
--   transaction.
submitDependentTask :: Pool a -> Handle -> IO a -> STM Handle

-- | Cancel a task submitted to the pool. This will unschedule it if it had
--   not begun yet, or cancel its thread if it had.
cancelTask :: Pool a -> Handle -> IO ()

-- | Given parent and child task handles, link them so that the child
--   cannot execute until the parent has finished.
sequenceTasks :: Pool a -> Handle -> Handle -> STM ()

-- | Wait until the given task is completed, but re-raise any exceptions
--   that were raised in the task's thread.
waitTask :: Pool a -> Handle -> STM a

-- | Wait until the given task has completed, then return its final status.
waitTaskEither :: Pool a -> Handle -> STM (Either SomeException a)

-- | Poll the given task, as with <a>pollTaskEither</a>, but re-raise any
--   exceptions that were raised in the task's thread.
pollTask :: Pool a -> Handle -> STM (Maybe a)

-- | Poll the given task, returning <a>Nothing</a> if it hasn't started yet
--   or is currently executing, and a <a>Just</a> value if a final result
--   is known.
pollTaskEither :: Pool a -> Handle -> STM (Maybe (Either SomeException a))