-- 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 -- termination. The result of a thread can also be retrieved, 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: -- http://hackage.haskell.org/package/threadmanager. The -- advantages of this package are: -- -- @package threads @version 0.1 -- | Standard threads extended with the ability to wait for their -- termination. -- -- This module exports equivalently named functions from -- Control.Concurrent. Avoid ambiguities by importing one or -- both qualified. We suggest importing this module like: -- -- 
--   import qualified Control.Concurrent.Thread as Thread ( ... )
--
module Control.Concurrent.Thread -- | A ThreadId α is an abstract type representing a handle -- to a thread that is executing or has executed a computation of type -- IO α. data ThreadId α -- | Extract the native Control.Concurrent.ThreadId. threadId :: ThreadId α -> ThreadId -- | Sparks off a new thread to run the given IO computation and -- returns the ThreadId of the newly created 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 α) -- | Like forkIO, this sparks off a new thread to run the given -- IO computation and returns the ThreadId of the newly -- created 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 α) -- | Block until the given thread is terminated. -- -- wait :: ThreadId α -> IO (Either SomeException α) -- | Like wait but will ignore the value returned by the thread. wait_ :: ThreadId α -> IO () -- | Like wait but will either rethrow the exception that was thrown -- in the thread or return the value that was returned by the thread. unsafeWait :: ThreadId α -> IO α -- | Like unsafeWait in that it will rethrow the exception that was -- thrown in the thread but it will ignore the value returned by the -- thread. unsafeWait_ :: ThreadId α -> IO () -- | A non-blocking wait. -- -- -- -- Notice that this observation is only a snapshot of a thread's state. -- By the time a program reacts on its result it may already be out of -- date. status :: ThreadId α -> IO (Maybe (Either SomeException α)) -- | Returns True if the thread is currently running and -- False otherwise. -- -- Notice that this observation is only a snapshot of a thread's state. -- By the time a program reacts on its result it may already be out of -- date. isRunning :: ThreadId α -> IO Bool -- | throwTo raises an arbitrary exception in the target thread (GHC -- only). -- -- throwTo does not return until the exception has been raised in -- the target thread. The calling thread can thus be certain that the -- target thread has received the exception. This is a useful property to -- know when dealing with race conditions: eg. if there are two threads -- that can kill each other, it is guaranteed that only one of the -- threads will get to kill the other. -- -- If the target thread is currently making a foreign call, then the -- exception will not be raised (and hence throwTo will not -- return) until the call has completed. This is the case regardless of -- whether the call is inside a block or not. -- -- Important note: the behaviour of throwTo differs from that -- described in the paper "Asynchronous exceptions in Haskell" -- (http://research.microsoft.com/~simonpj/Papers/asynch-exns.htm). -- In the paper, throwTo is non-blocking; but the library -- implementation adopts a more synchronous design in which -- throwTo does not return until the exception is received by the -- target thread. The trade-off is discussed in Section 9 of the paper. -- Like any blocking operation, throwTo is therefore interruptible -- (see Section 5.3 of the paper). -- -- There is currently no guarantee that the exception delivered by -- throwTo will be delivered at the first possible opportunity. In -- particular, a thread may unblock and then re-block -- exceptions without receiving a pending throwTo. This is -- arguably undesirable behaviour. throwTo :: (Exception e) => ThreadId α -> e -> IO () -- | killThread terminates the given thread (GHC only). Any work -- already done by the thread isn't lost: the computation is suspended -- until required by another thread. The memory used by the thread will -- be garbage collected if it isn't referenced from anywhere. The -- killThread function is defined in terms of throwTo. -- -- Note that this function is different than -- Control.Concurrent.killThread in that it blocks until -- the target thread is terminated: -- -- 
--   killThread tid = throwTo tid ThreadKilled >> wait_ tid
--
killThread :: ThreadId α -> 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 and Control.Concurrent.Thread. -- Avoid ambiguities by importing one or both qualified. We suggest -- importing this module like: -- -- 
--   import Control.Concurrent.Thread.Group ( ThreadGroup )
--   import qualified Control.Concurrent.Thread.Group as ThreadGroup ( ... )
--
module Control.Concurrent.Thread.Group data ThreadGroup -- | Create a new empty group. new :: IO ThreadGroup -- | Same as Control.Concurrent.Thread.forkIO but -- additionaly adds the thread to the group. forkIO :: ThreadGroup -> IO α -> IO (ThreadId α) -- | Same as Control.Concurrent.Thread.forkOS but -- additionaly adds the thread to the group. forkOS :: ThreadGroup -> IO α -> IO (ThreadId α) -- | Block until all threads, that were added to the group before calling -- this function, have terminated. wait :: ThreadGroup -> IO () -- | Returns True if any thread in the group is running and returns -- False otherwise. -- -- Notice that this observation is only a snapshot of a group's state. By -- the time a program reacts on its result it may already be out of date. isAnyRunning :: ThreadGroup -> IO Bool instance Typeable ThreadGroup