async-stm-0.1.0.0

Safe HaskellSafe-Infered

Control.Concurrent.Async

Contents

Synopsis

Async API

data Async a Source

An asynchronous action spawned by async or withAsync. Asynchronous actions are executed in a separate thread, and operations are provided for waiting for asynchronous actions to complete and obtaining their results (see e.g. wait).

Instances

Eq (Async a) 
Ord (Async a) 

async :: IO a -> IO (Async a)Source

spawn an asynchronous action in a separate thread.

withAsync :: IO a -> (Async a -> IO b) -> IO bSource

spawn an asynchronous action in a separate thread, and pass its Async handle to the supplied function. When the function returns or throws an exception, cancel is called on the Async.

 withAsync action inner = bracket (async action) cancel inner

This is a useful variant of async that ensures an Async is never left running unintentionally.

wait :: Async a -> IO (Either SomeException a)Source

wait for an asynchronous action to complete, and return either Left e if the action raise an exception e, or Right a if it returned a value a.

 wait = atomically . waitSTM

waitThrow :: Async a -> IO aSource

A version of wait that throws the exception if the asynchronous action raised one, or otherwise returns its result.

 waitThrow = atomically . waitSTMThrow

cancel :: Async a -> IO ()Source

Cancel an asynchronous action by throwing the ThreadKilled exception to it.

cancelWith :: Exception e => Async a -> e -> IO ()Source

Cancel an asynchronous action by throwing the supplied exception to it.

STM API

waitSTM :: Async a -> STM (Either SomeException a)Source

A version of wait that can be used inside an STM transaction.

waitSTMThrow :: Async a -> STM aSource

A version of waitThrow that can be used inside an STM transaction.

Waiting for multiple asyncs

waitAny :: [Async a] -> IO ()Source

Wait for any of the supplied asynchronous operations to complete.

waitAnyThrow :: [Async a] -> IO ()Source

Wait for any of the supplied Asyncs to complete. If the first to complete raises an exception, then that exception is re-thrown by waitAnyThrow.

waitAnyThrowCancel :: [Async a] -> IO ()Source

like waitAnyThrow, but also cancels the other asynchronous operations as soon as one has completed.

waitEither :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b))Source

Wait for the first of two Asyncs to finish.

waitEitherThrow :: Async a -> Async b -> IO (Either a b)Source

Wait for the first of two Asyncs to finish. If the first Async to finish raised an exception, then the exception is re-thrown by waitEitherThrow.

waitEitherThrow_ :: Async a -> Async b -> IO ()Source

Like waitEitherThrow, but the results are ignored.

waitEitherThrowCancel :: Async a -> Async b -> IO (Either a b)Source

like waitEitherThow, but also cancels both Asyncs before returning.

waitBothThrow :: Async a -> Async b -> IO (a, b)Source

waits for both Asyncs to finish, but if either of them throws an exception before they have both finished, then the exception is re-thrown by waitBothThow

Linking

link :: Async a -> IO ()Source

Link the given Async to the current thread, such that if the Async raises an exception, that exception will be re-thrown in the current thread.

link2 :: Async a -> Async b -> IO ()Source

Link two Asyncs together, such that if either raises an exception, the same exception is re-thrown in the other Async.

Convenient utilities

race :: IO a -> IO b -> IO (Either a b)Source

run two IO actions concurrently, and return the first to finish. The loser of the race is cancelled.

 race left right =
   withAsync left $ \a ->
   withAsync right $ \b ->
   waitEitherThrow a b

race_ :: IO a -> IO b -> IO ()Source

like race, but the result is ignored.

concurrently :: IO a -> IO b -> IO (a, b)Source

run two IO actions concurrently, and return both results. If either action throws an exception at any time, then the other action is cancelled, and the exception is re-thrown by concurrently.

 concurrently left right =
   withAsync left $ \a ->
   withAsync right $ \b ->
   waitBothThrow a b