-- 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.0.2


-- | 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 α -> IO (ThreadId, IO (Result α))

-- | 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 α -> IO (ThreadId, IO (Result α))

-- | 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 α -> IO (ThreadId, IO (Result α))

-- | 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 β. IO β -> IO β) -> IO α) -> IO (ThreadId, IO (Result α))

-- | 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 β. IO β -> IO β) -> IO α) -> IO (ThreadId, IO (Result α))

-- | 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 α = Either SomeException α

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


-- | 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 not 0.</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

-- | Convenience function which blocks until all threads, that were added
--   to the group have terminated.
wait :: ThreadGroup -> IO ()

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

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

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

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

-- | Like <tt>Control.Concurrent.Thread.<a>forkOnWithUnmask</a></tt> but
--   additionaly adds the thread to the group.
forkOnWithUnmask :: Int -> ThreadGroup -> ((forall β. IO β -> IO β) -> IO α) -> IO (ThreadId, IO (Result α))
instance Typeable ThreadGroup
instance Eq ThreadGroup
