-- 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 <tt>threadmanager</tt>, <tt>async</tt>
--   and <tt>spawn</tt> packages. The advantages of this package are:
--   
--   <ul>
--   <li>Simpler API.</li>
--   <li>More efficient in both space and time.</li>
--   <li>No space-leak when forking a large number of threads.</li>
--   <li>Correct handling of asynchronous exceptions.</li>
--   <li>GHC specific functionality like <tt>forkOn</tt> and
--   <tt>forkIOWithUnmask</tt>.</li>
--   </ul>
@package threads
@version 0.5.1.5


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

-- | Like <tt>Control.Concurrent.<a>forkIO</a></tt> 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 <tt>Control.Concurrent.<a>forkOS</a></tt> 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 <tt>Control.Concurrent.<a>forkOn</a></tt> 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 <tt>Control.Concurrent.<a>forkIOWithUnmask</a></tt> 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 <tt>Control.Concurrent.<a>forkOnWithUnmask</a></tt> 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 <a>SomeException</a> the exception is thrown.
result :: Result a -> IO a


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

-- | A <tt>ThreadGroup</tt> 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 <tt>ThreadGroup</tt> has the following semantics:
--   
--   <ul>
--   <li><a>new</a> initializes the counter to 0.</li>
--   <li>Forking a thread increments the counter.</li>
--   <li>When a forked thread terminates, whether normally or by raising an
--   exception, the counter is decremented.</li>
--   <li><a>nrOfRunning</a> yields a transaction that returns the
--   counter.</li>
--   <li><a>wait</a> blocks as long as the counter is greater than 0.</li>
--   <li><a>waitN</a> blocks as long as the counter is greater or equal to
--   the specified number.</li>
--   </ul>
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 <a>STM</a> 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: <tt>wait = <a>waitN</a> 1</tt>.
wait :: ThreadGroup -> IO ()

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

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

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

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

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

-- | Like <tt>Control.Concurrent.Thread.<a>forkOnWithUnmask</a></tt> 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
