Control.Concurrent.Thread

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 result of a thread

data Result α

A Result α is an abstract type representing the result of a thread that is executing or has executed a computation of type IO α.

Instances

Typeable1 Result

Forking threads

forkIO :: IO α -> IO (ThreadId, Result α)

Sparks off a new thread to run the given IO computation and returns the ThreadId of the newly created thread paired with the Result of the thread which can be waited upon.

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

forkOS :: IO α -> IO (ThreadId, 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 the Result of the thread which can be waited upon.

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.

forkOnIO :: Int -> IO α -> IO (ThreadId, 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).

Waiting for results

wait :: Result α -> IO (Either SomeException α)

Block until the thread, to which the given Result belongs, is terminated.

• Returns Right x if the thread terminated normally and returned x.
• Returns Left e if some exception e was thrown in the thread and wasn't caught.

wait_ :: Result α -> IO ()

Like wait but will ignore the value returned by the thread.

unsafeWait :: Result α -> 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_ :: Result α -> 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.

Querying results

status :: Result α -> IO (Maybe (Either SomeException α))

A non-blocking wait.

• Returns Nothing if the thread is still running.
• Returns Just (Right x) if the thread terminated normally and returned x.
• Returns Just (Left e) if some exception e was thrown in the thread and wasn't caught.

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 :: Result α -> IO Bool

If the thread, to which the given Result belongs, is currently running return True and return 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.