Core.Program.Threads

Utility functions for running Program actions concurrently.

Haskell uses green threads: small lines of work that are scheduled down onto actual execution contexts (set by default by this library to be one per core). Haskell threads are incredibly lightweight, and you are encouraged to use them freely. Haskell provides a rich ecosystem of tools to do work concurrently and to communicate safely between threads.

This module provides wrappers around some of these primatives so you can use them easily from the Program monad.

Note that when you fire off a new thread the top-level application state is shared; it's the same τ inherited from the parent Program.

Concurrency

forkThread :: Program τ α -> Program τ (Thread α)

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

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

waitThread :: Thread α -> Program τ α

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

(this wraps async's wait)

waitThread_ :: Thread α -> Program τ ()

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.

Helper functions

concurrentThreads :: Program τ α -> Program τ β -> Program τ (α, β)

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)

concurrentThreads_ :: Program τ α -> Program τ β -> Program τ ()

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

raceThreads :: Program τ α -> Program τ β -> Program τ (Either α β)

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)

raceThreads_ :: Program τ α -> Program τ β -> Program τ ()

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

Internals

data Thread α

A thread for concurrent computation.

(this wraps async's Async)