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

-- | Fork threads and wait for their result
--   
--   This package provides functions to fork threads and wait for their
--   result, whether it's an exception or a normal value.
--   
--   Besides waiting for the termination of a single thread this packages
--   also provides functions to wait for a group of threads to terminate.
--   
--   This package is similar to the threadmanager, async
--   and spawn packages. The advantages of this package are:
--   
--   
--   
- Simpler API.
--   
- More efficient in both space and time.
--   
- No space-leak when forking a large number of threads.
--   
- Correct handling of asynchronous exceptions.
--   
- GHC specific functionality like forkOn and
--   forkIOWithUnmask.
--   
@package threads
@version 0.5.1.8

-- | Standard threads extended with the ability to wait for their
--   return value.
--   
--   This module exports equivalently named functions from
--   Control.Concurrent (and GHC.Conc). Avoid ambiguities
--   by importing this module qualified. May we suggest:
--   
--   
--   import qualified Control.Concurrent.Thread as Thread ( ... )
--   
--   
--   The following is an example how to use this module:
--   
--   
--   import qualified Control.Concurrent.Thread as Thread ( forkIO, result )
--   
--   main = do (tid, wait) <- Thread.forkIO $ do x <- someExpensiveComputation
--                                              return x
--            doSomethingElse
--            x <- Thread.result =<< wait
--            doSomethingWithResult x
--   
module Control.Concurrent.Thread

-- | Like Control.Concurrent.forkIO but returns a
--   computation that when executed blocks until the thread terminates then
--   returns the final value of the thread.
forkIO :: IO a -> IO (ThreadId, IO (Result a))

-- | Like Control.Concurrent.forkOS but returns a
--   computation that when executed blocks until the thread terminates then
--   returns the final value of the thread.
forkOS :: IO a -> IO (ThreadId, IO (Result a))

-- | Like Control.Concurrent.forkOn but returns a
--   computation that when executed blocks until the thread terminates then
--   returns the final value of the thread.
forkOn :: Int -> IO a -> IO (ThreadId, IO (Result a))

-- | Like Control.Concurrent.forkIOWithUnmask but returns a
--   computation that when executed blocks until the thread terminates then
--   returns the final value of the thread.
forkIOWithUnmask :: ((forall b. () => IO b -> IO b) -> IO a) -> IO (ThreadId, IO (Result a))

-- | Like Control.Concurrent.forkOnWithUnmask but returns a
--   computation that when executed blocks until the thread terminates then
--   returns the final value of the thread.
forkOnWithUnmask :: Int -> ((forall b. () => IO b -> IO b) -> IO a) -> IO (ThreadId, IO (Result a))

-- | A result of a thread is either some exception that was thrown in the
--   thread and wasn't catched or the actual value that was returned by the
--   thread.
type Result a = Either SomeException a

-- | Retrieve the actual value from the result.
--   
--   When the result is SomeException the exception is thrown.
result :: Result a -> IO a

-- | This module extends Control.Concurrent.Thread with the
--   ability to wait for a group of threads to terminate.
--   
--   This module exports equivalently named functions from
--   Control.Concurrent, (GHC.Conc), and
--   Control.Concurrent.Thread. Avoid ambiguities by importing
--   this module qualified. May we suggest:
--   
--   
--   import Control.Concurrent.Thread.Group ( ThreadGroup )
--   import qualified Control.Concurrent.Thread.Group as ThreadGroup ( ... )
--   
module Control.Concurrent.Thread.Group

-- | A ThreadGroup can be understood as a counter which counts the
--   number of threads that were added to the group minus the ones that
--   have terminated.
--   
--   More formally a ThreadGroup has the following semantics:
--   
--   
--   
- new initializes the counter to 0.
--   
- Forking a thread increments the counter.
--   
- When a forked thread terminates, whether normally or by raising an
--   exception, the counter is decremented.
--   
- nrOfRunning yields a transaction that returns the
--   counter.
--   
- wait blocks as long as the counter is greater than 0.
--   
- waitN blocks as long as the counter is greater or equal to
--   the specified number.
--   
data ThreadGroup

-- | Create an empty group of threads.
new :: IO ThreadGroup

-- | Yield a transaction that returns the number of running threads in the
--   group.
--   
--   Note that because this function yields a STM computation, the
--   returned number is guaranteed to be consistent inside the transaction.
nrOfRunning :: ThreadGroup -> STM Int

-- | Block until all threads in the group have terminated.
--   
--   Note that: wait = waitN 1.
wait :: ThreadGroup -> IO ()

-- | Block until there are fewer than N running threads in the
--   group.
waitN :: Int -> ThreadGroup -> IO ()

-- | Same as Control.Concurrent.Thread.forkIO but
--   additionaly adds the thread to the group.
forkIO :: ThreadGroup -> IO a -> IO (ThreadId, IO (Result a))

-- | Same as Control.Concurrent.Thread.forkOS but
--   additionaly adds the thread to the group.
forkOS :: ThreadGroup -> IO a -> IO (ThreadId, IO (Result a))

-- | Same as Control.Concurrent.Thread.forkOn but
--   additionaly adds the thread to the group.
forkOn :: Int -> ThreadGroup -> IO a -> IO (ThreadId, IO (Result a))

-- | Same as Control.Concurrent.Thread.forkIOWithUnmask but
--   additionaly adds the thread to the group.
forkIOWithUnmask :: ThreadGroup -> ((forall b. () => IO b -> IO b) -> IO a) -> IO (ThreadId, IO (Result a))

-- | Like Control.Concurrent.Thread.forkOnWithUnmask but
--   additionaly adds the thread to the group.
forkOnWithUnmask :: Int -> ThreadGroup -> ((forall b. () => IO b -> IO b) -> IO a) -> IO (ThreadId, IO (Result a))
instance GHC.Classes.Eq Control.Concurrent.Thread.Group.ThreadGroup
