-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Combinators for executing IO actions in parallel on a thread pool.
--
-- This package provides combinators for sequencing IO actions onto a
-- thread pool. The thread pool is guaranteed to contain a fixed number
-- of unblocked threads, minimizing contention. Furthermore, the parallel
-- combinators can be used re-entrently - your parallel actions can spawn
-- more parallel actions - without violating this property.
--
-- The package is heavily inspired by the thread
-- http://thread.gmane.org/gmane.comp.lang.haskell.cafe/56499/focus=56521.
-- Thanks to Neil Mitchell and Bulat Ziganshin for the code this package
-- is based on.
@package parallel-io
@version 0.2.1
-- | Parallelism combinators with explicit thread-pool creation and
-- passing.
--
-- The most basic example of usage is:
--
--
-- main = withPool 2 $ \pool -> parallel_ pool [putStrLn "Echo", putStrLn " in parallel"]
--
--
-- Make sure that you compile with -threaded and supply +RTS
-- -N2 -RTS to the generated Haskell executable, or you won't get
-- any parallelism.
--
-- The Control.Concurrent.ParallelIO.Global module is implemented
-- on top of this one by maintaining a shared global thread pool with one
-- thread per capability.
module Control.Concurrent.ParallelIO.Local
-- | Type of work items you can put onto the queue. The Bool
-- returned from the IO action specifies whether the invoking
-- thread should terminate itself immediately.
type WorkItem = IO Bool
-- | A WorkQueue is used to communicate WorkItems to the
-- workers.
type WorkQueue = ConcurrentSet WorkItem
-- | The type of thread pools used by ParallelIO. The best way to
-- construct one of these is using withPool.
data Pool
-- | A safe wrapper around startPool and stopPool. Executes
-- an IO action using a newly-created pool with the specified
-- number of threads and cleans it up at the end.
withPool :: Int -> (Pool -> IO a) -> IO a
-- | A slightly unsafe way to construct a pool. Make a pool from the
-- maximum number of threads you wish it to execute (including the main
-- thread in the count).
--
-- If you use this variant then ensure that you insert a call to
-- stopPool somewhere in your program after all users of that pool
-- have finished.
--
-- A better alternative is to see if you can use the withPool
-- variant.
startPool :: Int -> IO Pool
-- | Clean up a thread pool. If you don't call this then no one holds the
-- queue, the queue gets GC'd, the threads find themselves blocked
-- indefinitely, and you get exceptions.
--
-- This cleanly shuts down the threads so the queue isn't important and
-- you don't get exceptions.
--
-- Only call this after all users of the pool have completed, or
-- your program may block indefinitely.
stopPool :: Pool -> IO ()
-- | Internal method for scheduling work on a pool.
enqueueOnPool :: Pool -> WorkItem -> IO ()
-- | Wrap any IO action used from your worker threads that may block with
-- this method: it temporarily spawns another worker thread to make up
-- for the loss of the old blocked worker.
--
-- This is particularly important if the unblocking is dependent on
-- worker threads actually doing work. If you have this situation, and
-- you don't use this method to wrap blocking actions, then you may get a
-- deadlock if all your worker threads get blocked on work that they
-- assume will be done by other worker threads.
extraWorkerWhileBlocked :: Pool -> IO () -> IO ()
-- | Internal method for adding extra unblocked threads to a pool if one is
-- going to be temporarily blocked.
spawnPoolWorkerFor :: Pool -> IO ()
-- | Internal method for removing threads from a pool after we become
-- unblocked.
killPoolWorkerFor :: Pool -> IO ()
-- | Run the list of computations in parallel.
--
-- Has the following properties:
--
--
-- - Never creates more or less unblocked threads than are specified to
-- live in the pool. NB: this count includes the thread executing
-- parallel_. This should minimize contention and hence
-- pre-emption, while also preventing starvation.
-- - On return all actions have been performed.
-- - The function returns in a timely manner as soon as all actions
-- have been performed.
-- - The above properties are true even if parallel_ is used by
-- an action which is itself being executed by parallel_.
--
parallel_ :: Pool -> [IO a] -> IO ()
-- | Run the list of computations in parallel, returning the results in the
-- same order as the corresponding actions.
--
-- Has the following properties:
--
--
-- - Never creates more or less unblocked threads than are specified to
-- live in the pool. NB: this count includes the thread executing
-- parallel_. This should minimize contention and hence
-- pre-emption, while also preventing starvation.
-- - On return all actions have been performed.
-- - The function returns in a timely manner as soon as all actions
-- have been performed.
-- - The above properties are true even if parallel is used by
-- an action which is itself being executed by parallel.
--
parallel :: Pool -> [IO a] -> IO [a]
-- | Run the list of computations in parallel, returning the results in the
-- approximate order of completion.
--
-- Has the following properties:
--
--
-- - Never creates more or less unblocked threads than are specified to
-- live in the pool. NB: this count includes the thread executing
-- parallel_. This should minimize contention and hence
-- pre-emption, while also preventing starvation.
-- - On return all actions have been performed.
-- - The result of running actions appear in the list in undefined
-- order, but which is likely to be very similar to the order of
-- completion.
-- - The above properties are true even if parallelInterleaved
-- is used by an action which is itself being executed by
-- parallelInterleaved.
--
parallelInterleaved :: Pool -> [IO a] -> IO [a]
-- | Parallelism combinators with an implicit global thread-pool.
--
-- The most basic example of usage is:
--
--
-- main = parallel_ [putStrLn "Echo", putStrLn " in parallel"] >> stopGlobalPool
--
--
-- Make sure that you compile with -threaded and supply +RTS
-- -N2 -RTS to the generated Haskell executable, or you won't get
-- any parallelism.
--
-- The Control.Concurrent.ParallelIO.Local module provides a more
-- general interface which allows explicit passing of pools and control
-- of their size. This module is implemented on top of that one by
-- maintaining a shared global thread pool with one thread per
-- capability.
module Control.Concurrent.ParallelIO.Global
globalPool :: Pool
-- | In order to reliably make use of the global parallelism combinators,
-- you must invoke this function after all calls to those combinators
-- have finished. A good choice might be at the end of main.
--
-- See also stopPool.
stopGlobalPool :: IO ()
-- | Wrap any IO action used from your worker threads that may block with
-- this method: it temporarily spawns another worker thread to make up
-- for the loss of the old blocked worker.
--
-- See also extraWorkerWhileBlocked.
extraWorkerWhileBlocked :: IO () -> IO ()
-- | Internal method for adding extra unblocked threads to a pool if one is
-- going to be temporarily blocked.
--
-- See also spawnPoolWorkerFor.
spawnPoolWorker :: IO ()
-- | Internal method for removing threads from a pool after we become
-- unblocked.
--
-- See also killPoolWorkerFor.
killPoolWorker :: IO ()
-- | Execute the given actions in parallel on the global thread pool.
--
-- See also parallel_.
parallel_ :: [IO a] -> IO ()
-- | Execute the given actions in parallel on the global thread pool,
-- returning the results in the same order as the corresponding actions.
--
-- See also parallel.
parallel :: [IO a] -> IO [a]
-- | Execute the given actions in parallel on the global thread pool,
-- returning the results in the approximate order of completion.
--
-- See also parallelInterleaved.
parallelInterleaved :: [IO a] -> IO [a]
module Control.Concurrent.ParallelIO