Fork a thread. The child thread will run in the same Context as the calling Program, including sharing the user-defined application state value.

If the code in the child thread throws an exception that is not caught within that thread, the exception will kill the thread. Threads dying without telling anyone is a bit of an anti-pattern, so this library logs a warning-level log message if this happens. If you additionally want the exception to propegate back to the parent thread (say, for example, you want your whole program to die if any of its worker threads fail), then call linkThread after forking.

(this wraps async's async which in turn wraps base's forkIO)

Since: 0.2.7

Wait for the completion of a thread, returning the result. This is a blocking operation.

(this wraps async's wait)

Since: 0.2.7

Wait for the completion of a thread, discarding its result. This is particularly useful at the end of a do-block if you're waiting on a worker thread to finish but don't need its return value, if any; otherwise you have to explicily deal with the unused return value:

    _ <- waitThread t1
    return ()

which is a bit tedious. Instead, you can just use this convenience function:

    waitThread_ t1

The trailing underscore in the name of this function follows the same convetion as found in Control.Monad, which has mapM_ which does the same as mapM but which likewise discards the return value.

Since: 0.2.7

Ordinarily if an exception is thrown in a forked thread that exception is silently swollowed. If you instead need the exception to propegate back to the parent thread, you can "link" the two together using this function.

(this wraps async's link)

Since: 0.4.2

Fork two threads and wait for both to finish. The return value is the pair of each action's return types.

This is the same as calling forkThread and waitThread twice, except that if either sub-program fails with an exception the other program which is still running will be cancelled and the original exception is then re-thrown.

    (a,b) <- concurrentThreads one two

    -- continue, doing something with both results.

For a variant that ingores the return values and just waits for both see concurrentThreads_ below.

(this wraps async's concurrently)

Since: 0.4.0

Fork two threads and wait for both to finish.

This is the same as calling forkThread and waitThread_ twice, except that if either sub-program fails with an exception the other program which is still running will be cancelled and the original exception is then re-thrown.

(this wraps async's concurrently_)

Since: 0.4.0

Fork two threads and race them against each other. This blocks until one or the other of the threads finishes. The return value will be Left α if the first program (one) completes first, and Right β if it is the second program (two) which finishes first. The sub program which is still running will be cancelled with an exception.

    result <- raceThreads one two
    case result of
        Left a -> do
            -- one finished first
        Right b -> do
            -- two finished first

For a variant that ingores the return value and just races the threads see raceThreads_ below.

(this wraps async's race)

Since: 0.4.0

Fork two threads and race them against each other. When one action completes the other will be cancelled with an exception. This is useful for enforcing timeouts:

    raceThreads_
        (sleepThread 300)
        (do
            -- We expect this to complete within 5 minutes.
            performAction
        )

(this wraps async's race_)

Since: 0.4.0

A thread for concurrent computation.

(this wraps async's Async)