Control.Concurrent.Async.Internal

This module is an internal module. The public API is provided in Control.Concurrent.Async. Breaking changes to this module will not be reflected in a major bump, and using this module may break your code unless you are extremely careful.

Documentation

data Async a

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

Constructors

Async

Fields

• asyncThreadId :: !ThreadId

  Returns the ThreadId of the thread running the given Async.

• _asyncWait :: STM (Either SomeException a)

Instances

Functor Async

Defined in Control.Concurrent.Async.Internal

Methods

fmap :: (a -> b) -> Async a -> Async b

(<$) :: a -> Async b -> Async a

Eq (Async a)

Defined in Control.Concurrent.Async.Internal

Methods

(==) :: Async a -> Async a -> Bool

(/=) :: Async a -> Async a -> Bool

Ord (Async a)

Defined in Control.Concurrent.Async.Internal

Methods

compare :: Async a -> Async a -> Ordering

(<) :: Async a -> Async a -> Bool

(<=) :: Async a -> Async a -> Bool

(>) :: Async a -> Async a -> Bool

(>=) :: Async a -> Async a -> Bool

max :: Async a -> Async a -> Async a

min :: Async a -> Async a -> Async a

Hashable (Async a)

Defined in Control.Concurrent.Async.Internal

Methods

hashWithSalt :: Int -> Async a -> Int

hash :: Async a -> Int

compareAsyncs :: Async a -> Async b -> Ordering

Compare two Asyncs that may have different types by their ThreadId.

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

Spawn an asynchronous action in a separate thread.

Like for forkIO, the action may be left running unintentionally (see module-level documentation for details).

Use withAsync style functions wherever you can instead!

asyncBound :: IO a -> IO (Async a)

Like async but using forkOS internally.

asyncOn :: Int -> IO a -> IO (Async a)

Like async but using forkOn internally.

asyncWithUnmask :: ((forall b. IO b -> IO b) -> IO a) -> IO (Async a)

Like async but using forkIOWithUnmask internally. The child thread is passed a function that can be used to unmask asynchronous exceptions.

asyncOnWithUnmask :: Int -> ((forall b. IO b -> IO b) -> IO a) -> IO (Async a)

Like asyncOn but using forkOnWithUnmask internally. The child thread is passed a function that can be used to unmask asynchronous exceptions.

asyncUsing :: (IO () -> IO ThreadId) -> IO a -> IO (Async a)

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

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, uninterruptibleCancel is called on the Async.

withAsync action inner = mask $ \restore -> do
  a <- async (restore action)
  restore (inner a) `finally` uninterruptibleCancel a

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

Note: a reference to the child thread is kept alive until the call to withAsync returns, so nesting many withAsync calls requires linear memory.

withAsyncBound :: IO a -> (Async a -> IO b) -> IO b

Like withAsync but uses forkOS internally.

withAsyncOn :: Int -> IO a -> (Async a -> IO b) -> IO b

Like withAsync but uses forkOn internally.

withAsyncWithUnmask :: ((forall c. IO c -> IO c) -> IO a) -> (Async a -> IO b) -> IO b

Like withAsync but uses forkIOWithUnmask internally. The child thread is passed a function that can be used to unmask asynchronous exceptions.

withAsyncOnWithUnmask :: Int -> ((forall c. IO c -> IO c) -> IO a) -> (Async a -> IO b) -> IO b

Like withAsyncOn but uses forkOnWithUnmask internally. The child thread is passed a function that can be used to unmask asynchronous exceptions

withAsyncUsing :: (IO () -> IO ThreadId) -> IO a -> (Async a -> IO b) -> IO b

wait :: Async a -> IO a

Wait for an asynchronous action to complete, and return its value. If the asynchronous action threw an exception, then the exception is re-thrown by wait.

wait = atomically . waitSTM

waitCatch :: Async a -> IO (Either SomeException a)

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

waitCatch = atomically . waitCatchSTM

poll :: Async a -> IO (Maybe (Either SomeException a))

Check whether an Async has completed yet. If it has not completed yet, then the result is Nothing, otherwise the result is Just e where e is Left x if the Async raised an exception x, or Right a if it returned a value a.

poll = atomically . pollSTM

waitSTM :: Async a -> STM a

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

waitCatchSTM :: Async a -> STM (Either SomeException a)

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

pollSTM :: Async a -> STM (Maybe (Either SomeException a))

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

cancel :: Async a -> IO ()

Cancel an asynchronous action by throwing the AsyncCancelled exception to it, and waiting for the Async thread to quit. Has no effect if the Async has already completed.

cancel a = throwTo (asyncThreadId a) AsyncCancelled <* waitCatch a

Note that cancel will not terminate until the thread the Async refers to has terminated. This means that cancel will block for as long said thread blocks when receiving an asynchronous exception.

For example, it could block if:

• It's executing a foreign call, and thus cannot receive the asynchronous exception;
• It's executing some cleanup handler after having received the exception, and the handler is blocking.

cancelMany :: [Async a] -> IO ()

Cancel multiple asynchronous actions by throwing the AsyncCancelled exception to each of them in turn, then waiting for all the Async threads to complete.

data AsyncCancelled

The exception thrown by cancel to terminate a thread.

Constructors

AsyncCancelled

Instances

Exception AsyncCancelled

Defined in Control.Concurrent.Async.Internal

Methods

toException :: AsyncCancelled -> SomeException

fromException :: SomeException -> Maybe AsyncCancelled

displayException :: AsyncCancelled -> String

Show AsyncCancelled

Defined in Control.Concurrent.Async.Internal

Methods

showsPrec :: Int -> AsyncCancelled -> ShowS

show :: AsyncCancelled -> String

showList :: [AsyncCancelled] -> ShowS

Eq AsyncCancelled

Defined in Control.Concurrent.Async.Internal

Methods

(==) :: AsyncCancelled -> AsyncCancelled -> Bool

(/=) :: AsyncCancelled -> AsyncCancelled -> Bool

uninterruptibleCancel :: Async a -> IO ()

Cancel an asynchronous action

This is a variant of cancel, but it is not interruptible.

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

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

cancelWith a x = throwTo (asyncThreadId a) x

The notes about the synchronous nature of cancel also apply to cancelWith.

waitAnyCatch :: [Async a] -> IO (Async a, Either SomeException a)

Wait for any of the supplied asynchronous operations to complete. The value returned is a pair of the Async that completed, and the result that would be returned by wait on that Async. The input list must be non-empty.

If multiple Asyncs complete or have completed, then the value returned corresponds to the first completed Async in the list.

waitAnyCatchSTM :: [Async a] -> STM (Async a, Either SomeException a)

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

Since: 2.1.0

waitAnyCatchCancel :: [Async a] -> IO (Async a, Either SomeException a)

Like waitAnyCatch, but also cancels the other asynchronous operations as soon as one has completed.

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

Wait for any of the supplied Asyncs to complete. If the first to complete throws an exception, then that exception is re-thrown by waitAny. The input list must be non-empty.

If multiple Asyncs complete or have completed, then the value returned corresponds to the first completed Async in the list.

waitAnySTM :: [Async a] -> STM (Async a, a)

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

Since: 2.1.0

waitAnyCancel :: [Async a] -> IO (Async a, a)

Like waitAny, but also cancels the other asynchronous operations as soon as one has completed.

waitEitherCatch :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b))

Wait for the first of two Asyncs to finish.

waitEitherCatchSTM :: Async a -> Async b -> STM (Either (Either SomeException a) (Either SomeException b))

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

Since: 2.1.0

waitEitherCatchCancel :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b))

Like waitEitherCatch, but also cancels both Asyncs before returning.

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

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

waitEitherSTM :: Async a -> Async b -> STM (Either a b)

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

Since: 2.1.0

waitEither_ :: Async a -> Async b -> IO ()

Like waitEither, but the result is ignored.

waitEitherSTM_ :: Async a -> Async b -> STM ()

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

Since: 2.1.0

waitEitherCancel :: Async a -> Async b -> IO (Either a b)

Like waitEither, but also cancels both Asyncs before returning.

waitBoth :: Async a -> Async b -> IO (a, b)

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

waitBothSTM :: Async a -> Async b -> STM (a, b)

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

Since: 2.1.0

data ExceptionInLinkedThread

Constructors

forall a. ExceptionInLinkedThread (Async a) SomeException

Instances

Exception ExceptionInLinkedThread

Defined in Control.Concurrent.Async.Internal

Methods

toException :: ExceptionInLinkedThread -> SomeException

fromException :: SomeException -> Maybe ExceptionInLinkedThread

displayException :: ExceptionInLinkedThread -> String

Show ExceptionInLinkedThread

Defined in Control.Concurrent.Async.Internal

Methods

showsPrec :: Int -> ExceptionInLinkedThread -> ShowS

show :: ExceptionInLinkedThread -> String

showList :: [ExceptionInLinkedThread] -> ShowS

link :: Async a -> IO ()

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, wrapped in ExceptionInLinkedThread.

link ignores AsyncCancelled exceptions thrown in the other thread, so that it's safe to cancel a thread you're linked to. If you want different behaviour, use linkOnly.

linkOnly

Arguments

:: (SomeException -> Bool)

return True if the exception should be propagated, False otherwise.

-> Async a

-> IO ()

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, wrapped in ExceptionInLinkedThread.

The supplied predicate determines which exceptions in the target thread should be propagated to the source thread.

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

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

link2 ignores AsyncCancelled exceptions, so that it's possible to cancel either thread without cancelling the other. If you want different behaviour, use link2Only.

link2Only :: (SomeException -> Bool) -> Async a -> Async b -> IO ()

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

The supplied predicate determines which exceptions in the target thread should be propagated to the source thread.

isCancel :: SomeException -> Bool

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

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 ->
  waitEither a b

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

Like race, but the result is ignored.

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

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 ->
  waitBoth a b

concurrentlyE :: IO (Either e a) -> IO (Either e b) -> IO (Either e (a, b))

Run two IO actions concurrently. If both of them end with Right, return both results. If one of then ends with Left, interrupt the other action and return the Left.

concurrently_ :: IO a -> IO b -> IO ()

concurrently, but ignore the result values

Since: 2.1.1

concurrently' :: IO a -> IO b -> (IO (Either SomeException (Either a b)) -> IO r) -> IO r

mapConcurrently :: Traversable t => (a -> IO b) -> t a -> IO (t b)

Maps an IO-performing function over any Traversable data type, performing all the IO actions concurrently, and returning the original data structure with the arguments replaced by the results.

If any of the actions throw an exception, then all other actions are cancelled and the exception is re-thrown.

For example, mapConcurrently works with lists:

pages <- mapConcurrently getURL ["url1", "url2", "url3"]

Take into account that async will try to immediately spawn a thread for each element of the Traversable, so running this on large inputs without care may lead to resource exhaustion (of memory, file descriptors, or other limited resources).

forConcurrently :: Traversable t => t a -> (a -> IO b) -> IO (t b)

forConcurrently is mapConcurrently with its arguments flipped

pages <- forConcurrently ["url1", "url2", "url3"] $ \url -> getURL url

Since: 2.1.0

mapConcurrently_ :: Foldable f => (a -> IO b) -> f a -> IO ()

mapConcurrently_ is mapConcurrently with the return value discarded; a concurrent equivalent of mapM_.

forConcurrently_ :: Foldable f => f a -> (a -> IO b) -> IO ()

forConcurrently_ is forConcurrently with the return value discarded; a concurrent equivalent of forM_.

replicateConcurrently :: Int -> IO a -> IO [a]

Perform the action in the given number of threads.

Since: 2.1.1

replicateConcurrently_ :: Int -> IO a -> IO ()

Same as replicateConcurrently, but ignore the results.

Since: 2.1.1

newtype Concurrently a

A value of type Concurrently a is an IO operation that can be composed with other Concurrently values, using the Applicative and Alternative instances.

Calling runConcurrently on a value of type Concurrently a will execute the IO operations it contains concurrently, before delivering the result of type a.

For example

(page1, page2, page3)
    <- runConcurrently $ (,,)
    <$> Concurrently (getURL "url1")
    <*> Concurrently (getURL "url2")
    <*> Concurrently (getURL "url3")

Constructors

Concurrently

Fields

• runConcurrently :: IO a

Instances

Alternative Concurrently

empty waits forever. <|> returns the first to finish and cancels the other.

Defined in Control.Concurrent.Async.Internal

Methods

empty :: Concurrently a

(<|>) :: Concurrently a -> Concurrently a -> Concurrently a

some :: Concurrently a -> Concurrently [a]

many :: Concurrently a -> Concurrently [a]

Applicative Concurrently

Defined in Control.Concurrent.Async.Internal

Methods

pure :: a -> Concurrently a

(<*>) :: Concurrently (a -> b) -> Concurrently a -> Concurrently b

liftA2 :: (a -> b -> c) -> Concurrently a -> Concurrently b -> Concurrently c

(*>) :: Concurrently a -> Concurrently b -> Concurrently b

(<*) :: Concurrently a -> Concurrently b -> Concurrently a

Functor Concurrently

Defined in Control.Concurrent.Async.Internal

Methods

fmap :: (a -> b) -> Concurrently a -> Concurrently b

(<$) :: a -> Concurrently b -> Concurrently a

(Semigroup a, Monoid a) => Monoid (Concurrently a)

Since: 2.1.0

Defined in Control.Concurrent.Async.Internal

Methods

mempty :: Concurrently a

mappend :: Concurrently a -> Concurrently a -> Concurrently a

mconcat :: [Concurrently a] -> Concurrently a

Semigroup a => Semigroup (Concurrently a)

Only defined by async for base >= 4.9

Since: 2.1.0

Defined in Control.Concurrent.Async.Internal

Methods

(<>) :: Concurrently a -> Concurrently a -> Concurrently a

sconcat :: NonEmpty (Concurrently a) -> Concurrently a

stimes :: Integral b => b -> Concurrently a -> Concurrently a

newtype ConcurrentlyE e a

A value of type ConcurrentlyE e a is an IO operation that can be composed with other ConcurrentlyE values, using the Applicative instance.

Calling runConcurrentlyE on a value of type ConcurrentlyE e a will execute the IO operations it contains concurrently, before delivering either the result of type a, or an error of type e if one of the actions returns Left.

| @since 2.2.5

Constructors

ConcurrentlyE

Fields

• runConcurrentlyE :: IO (Either e a)

Instances

Bifunctor ConcurrentlyE

Defined in Control.Concurrent.Async.Internal

Methods

bimap :: (a -> b) -> (c -> d) -> ConcurrentlyE a c -> ConcurrentlyE b d

first :: (a -> b) -> ConcurrentlyE a c -> ConcurrentlyE b c

second :: (b -> c) -> ConcurrentlyE a b -> ConcurrentlyE a c

Applicative (ConcurrentlyE e)

Defined in Control.Concurrent.Async.Internal

Methods

pure :: a -> ConcurrentlyE e a

(<*>) :: ConcurrentlyE e (a -> b) -> ConcurrentlyE e a -> ConcurrentlyE e b

liftA2 :: (a -> b -> c) -> ConcurrentlyE e a -> ConcurrentlyE e b -> ConcurrentlyE e c

(*>) :: ConcurrentlyE e a -> ConcurrentlyE e b -> ConcurrentlyE e b

(<*) :: ConcurrentlyE e a -> ConcurrentlyE e b -> ConcurrentlyE e a

Functor (ConcurrentlyE e)

Defined in Control.Concurrent.Async.Internal

Methods

fmap :: (a -> b) -> ConcurrentlyE e a -> ConcurrentlyE e b

(<$) :: a -> ConcurrentlyE e b -> ConcurrentlyE e a

(Semigroup a, Monoid a) => Monoid (ConcurrentlyE e a)

Defined in Control.Concurrent.Async.Internal

Methods

mempty :: ConcurrentlyE e a

mappend :: ConcurrentlyE e a -> ConcurrentlyE e a -> ConcurrentlyE e a

mconcat :: [ConcurrentlyE e a] -> ConcurrentlyE e a

Semigroup a => Semigroup (ConcurrentlyE e a)

Either the combination of the successful results, or the first failure.

Defined in Control.Concurrent.Async.Internal

Methods

(<>) :: ConcurrentlyE e a -> ConcurrentlyE e a -> ConcurrentlyE e a

sconcat :: NonEmpty (ConcurrentlyE e a) -> ConcurrentlyE e a

stimes :: Integral b => b -> ConcurrentlyE e a -> ConcurrentlyE e a

forkRepeat :: IO a -> IO ThreadId

Fork a thread that runs the supplied action, and if it raises an exception, re-runs the action. The thread terminates only when the action runs to completion without raising an exception.

catchAll :: IO a -> (SomeException -> IO a) -> IO a

tryAll :: IO a -> IO (Either SomeException a)

rawForkIO :: IO () -> IO ThreadId

rawForkOn :: Int -> IO () -> IO ThreadId