-- 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 and -- async packages. The advantages of this package are: -- -- @package threads @version 0.3 -- | Standard threads extended with the ability to wait for their -- termination. -- -- 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, unsafeResult )
--   
--   main = do (tid, wait) <- Thread.forkIO $ do x <- someExpensiveComputation
--                                               return x
--             doSomethingElse
--             x <- Thread.unsafeResult =<< wait
--             doSomethingWithResult x
--
module Control.Concurrent.Thread -- | Sparks off a new thread to run the given IO computation and -- returns the ThreadId of the newly created thread paired with an -- IO computation that waits for the result of the thread. -- -- The new thread will be a lightweight thread; if you want to use a -- foreign library that uses thread-local storage, use forkOS -- instead. -- -- GHC note: the new thread inherits the blocked state of the parent (see -- block). forkIO :: IO α -> IO (ThreadId, IO (Result α)) -- | Like forkIO, this sparks off a new thread to run the given -- IO computation and returns the ThreadId of the newly -- created thread paired with an IO computation that waits for the result -- of the thread. -- -- Unlike forkIO, forkOS creates a bound thread, -- which is necessary if you need to call foreign (non-Haskell) libraries -- that make use of thread-local state, such as OpenGL (see -- Control.Concurrent). -- -- Using forkOS instead of forkIO makes no difference at -- all to the scheduling behaviour of the Haskell runtime system. It is a -- common misconception that you need to use forkOS instead of -- forkIO to avoid blocking all the Haskell threads when making a -- foreign call; this isn't the case. To allow foreign calls to be made -- without blocking all the Haskell threads (with GHC), it is only -- necessary to use the -threaded option when linking your -- program, and to make sure the foreign import is not marked -- unsafe. forkOS :: IO α -> IO (ThreadId, IO (Result α)) -- | Like forkIO, but lets you specify on which CPU the thread is -- created. Unlike a forkIO thread, a thread created by -- forkOnIO will stay on the same CPU for its entire lifetime -- (forkIO threads can migrate between CPUs according to the -- scheduling policy). forkOnIO is useful for overriding the -- scheduling policy when you know in advance how best to distribute the -- threads. -- -- The Int argument specifies the CPU number; it is interpreted -- modulo numCapabilities (note that it actually specifies a -- capability number rather than a CPU number, but to a first -- approximation the two are equivalent). forkOnIO :: Int -> 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 α -- | Unsafely retrieve the actual value from the result. -- -- When the result is SomeException the exception stored inside of -- the SomeException is rethrown in the current thread. unsafeResult :: Result α -> IO α -- | 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: -- -- 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 Integer -- | Same as Control.Concurrent.Thread.forkIO but -- additionaly adds the thread to the group. forkIO :: ThreadGroup -> IO α -> IO (ThreadId, IO (Result α)) -- | Same as Control.Concurrent.Thread.forkOS but -- additionaly adds the thread to the group. forkOS :: ThreadGroup -> IO α -> IO (ThreadId, IO (Result α)) -- | Same as Control.Concurrent.Thread.forkOnIO but -- additionaly adds the thread to the group. (GHC only) forkOnIO :: Int -> ThreadGroup -> IO α -> IO (ThreadId, IO (Result α)) -- | Convenience function which blocks until all threads, that were added -- to the group have terminated. wait :: ThreadGroup -> IO () instance Typeable ThreadGroup