Control.Concurrent.Async.Lifted

lifted-async-0.10.2.7: Run lifted IO operations asynchronously and wait for their results

Copyright | Copyright (C) 2012-2018 Mitsutoshi Aoe
License | BSD-style (see the file LICENSE)
Maintainer | Mitsutoshi Aoe <maoe@foldr.in>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Control.Concurrent.Async.Lifted

Contents

- Asynchronous actions
  - Spawning
  - Spawning with automatic `cancel`ation
  - Quering `Async`s
  - STM operations
  - Waiting for multiple `Async`s
  - Waiting for multiple `Async`s in STM
  - Linking
- Convenient utilities

Description

This is a wrapped version of `Control.Concurrent.Async` with types generalized from `IO` to all monads in either `MonadBase` or `MonadBaseControl`.

All the functions restore the monadic effects in the forked computation unless specified otherwise.

If your monad stack satisfies ``StM` m a ~ a` (e.g. the reader monad), consider using `Control.Concurrent.Async.Lifted.Safe` module, which prevents you from messing up monadic effects.

Synopsis

- data Async a
- async :: MonadBaseControl IO m => m a -> m (Async (StM m a))
- asyncBound :: MonadBaseControl IO m => m a -> m (Async (StM m a))
- asyncOn :: MonadBaseControl IO m => Int -> m a -> m (Async (StM m a))
- asyncWithUnmask :: MonadBaseControl IO m => ((forall b. m b -> m b) -> m a) -> m (Async (StM m a))
- asyncOnWithUnmask :: MonadBaseControl IO m => Int -> ((forall b. m b -> m b) -> m a) -> m (Async (StM m a))
- withAsync :: MonadBaseControl IO m => m a -> (Async (StM m a) -> m b) -> m b
- withAsyncBound :: MonadBaseControl IO m => m a -> (Async (StM m a) -> m b) -> m b
- withAsyncOn :: MonadBaseControl IO m => Int -> m a -> (Async (StM m a) -> m b) -> m b
- withAsyncWithUnmask :: MonadBaseControl IO m => ((forall c. m c -> m c) -> m a) -> (Async (StM m a) -> m b) -> m b
- withAsyncOnWithUnmask :: MonadBaseControl IO m => Int -> ((forall c. m c -> m c) -> m a) -> (Async (StM m a) -> m b) -> m b
- wait :: MonadBaseControl IO m => Async (StM m a) -> m a
- poll :: MonadBaseControl IO m => Async (StM m a) -> m (Maybe (Either SomeException a))
- waitCatch :: MonadBaseControl IO m => Async (StM m a) -> m (Either SomeException a)
- cancel :: MonadBase IO m => Async a -> m ()
- uninterruptibleCancel :: MonadBase IO m => Async a -> m ()
- cancelWith :: (MonadBase IO m, Exception e) => Async a -> e -> m ()
- asyncThreadId :: Async a -> ThreadId
- data AsyncCancelled = AsyncCancelled
- waitSTM :: Async a -> STM a
- pollSTM :: Async a -> STM (Maybe (Either SomeException a))
- waitCatchSTM :: Async a -> STM (Either SomeException a)
- waitAny :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), a)
- waitAnyCatch :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), Either SomeException a)
- waitAnyCancel :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), a)
- waitAnyCatchCancel :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), Either SomeException a)
- waitEither :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either a b)
- waitEitherCatch :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either (Either SomeException a) (Either SomeException b))
- waitEitherCancel :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either a b)
- waitEitherCatchCancel :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either (Either SomeException a) (Either SomeException b))
- waitEither_ :: MonadBase IO m => Async a -> Async b -> m ()
- waitBoth :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (a, b)
- waitAnySTM :: [Async a] -> STM (Async a, a)
- waitAnyCatchSTM :: [Async a] -> STM (Async a, Either SomeException a)
- waitEitherSTM :: Async a -> Async b -> STM (Either a b)
- waitEitherCatchSTM :: Async a -> Async b -> STM (Either (Either SomeException a) (Either SomeException b))
- waitEitherSTM_ :: Async a -> Async b -> STM ()
- waitBothSTM :: Async a -> Async b -> STM (a, b)
- link :: MonadBase IO m => Async a -> m ()
- link2 :: MonadBase IO m => Async a -> Async b -> m ()
- data ExceptionInLinkedThread = ExceptionInLinkedThread (Async a) SomeException
- race :: MonadBaseControl IO m => m a -> m b -> m (Either a b)
- race_ :: MonadBaseControl IO m => m a -> m b -> m ()
- concurrently :: MonadBaseControl IO m => m a -> m b -> m (a, b)
- concurrently_ :: MonadBaseControl IO m => m a -> m b -> m ()
- mapConcurrently :: (Traversable t, MonadBaseControl IO m) => (a -> m b) -> t a -> m (t b)
- mapConcurrently_ :: (Foldable t, MonadBaseControl IO m) => (a -> m b) -> t a -> m ()
- forConcurrently :: (Traversable t, MonadBaseControl IO m) => t a -> (a -> m b) -> m (t b)
- forConcurrently_ :: (Foldable t, MonadBaseControl IO m) => t a -> (a -> m b) -> m ()
- replicateConcurrently :: MonadBaseControl IO m => Int -> m a -> m [a]
- replicateConcurrently_ :: MonadBaseControl IO m => Int -> m a -> m ()
- newtype Concurrently (m :: Type -> Type) a = Concurrently {
  - runConcurrently :: m a
  }
- compareAsyncs :: Async a -> Async b -> Ordering

# Asynchronous actions

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

#### Instances

Instances details

Functor Async |
Instance details Defined in Control.Concurrent.Async.Internal Methods fmap :: (a -> b) -> Async a -> Async b # (<$) :: a -> Async b -> Async a #
Eq (Async a) |
Instance details Defined in Control.Concurrent.Async.Internal Methods (==) :: Async a -> Async a -> Bool # (/=) :: Async a -> Async a -> Bool #
Ord (Async a) |
Instance details 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) |
Instance details Defined in Control.Concurrent.Async.Internal Methods hashWithSalt :: Int -> Async a -> Int # hash :: Async a -> Int #

## Spawning

async :: MonadBaseControl IO m => m a -> m (Async (StM m a)) #

Generalized version of `async`.

asyncBound :: MonadBaseControl IO m => m a -> m (Async (StM m a)) #

Generalized version of `asyncBound`.

asyncOn :: MonadBaseControl IO m => Int -> m a -> m (Async (StM m a)) #

Generalized version of `asyncOn`.

asyncWithUnmask :: MonadBaseControl IO m => ((forall b. m b -> m b) -> m a) -> m (Async (StM m a)) #

Generalized version of `asyncWithUnmask`.

asyncOnWithUnmask :: MonadBaseControl IO m => Int -> ((forall b. m b -> m b) -> m a) -> m (Async (StM m a)) #

Generalized version of `asyncOnWithUnmask`.

## Spawning with automatic `cancel`ation

withAsync :: MonadBaseControl IO m => m a -> (Async (StM m a) -> m b) -> m b #

Generalized version of `withAsync`.

withAsyncBound :: MonadBaseControl IO m => m a -> (Async (StM m a) -> m b) -> m b #

Generalized version of `withAsyncBound`.

withAsyncOn :: MonadBaseControl IO m => Int -> m a -> (Async (StM m a) -> m b) -> m b #

Generalized version of `withAsyncOn`.

withAsyncWithUnmask :: MonadBaseControl IO m => ((forall c. m c -> m c) -> m a) -> (Async (StM m a) -> m b) -> m b #

Generalized version of `withAsyncWithUnmask`.

withAsyncOnWithUnmask :: MonadBaseControl IO m => Int -> ((forall c. m c -> m c) -> m a) -> (Async (StM m a) -> m b) -> m b #

Generalized version of `withAsyncOnWithUnmask`.

## Quering `Async`s

wait :: MonadBaseControl IO m => Async (StM m a) -> m a #

Generalized version of `wait`.

poll :: MonadBaseControl IO m => Async (StM m a) -> m (Maybe (Either SomeException a)) #

Generalized version of `poll`.

waitCatch :: MonadBaseControl IO m => Async (StM m a) -> m (Either SomeException a) #

Generalized version of `waitCatch`.

cancel :: MonadBase IO m => Async a -> m () #

Generalized version of `cancel`.

uninterruptibleCancel :: MonadBase IO m => Async a -> m () #

Generalized version of `uninterruptibleCancel`.

cancelWith :: (MonadBase IO m, Exception e) => Async a -> e -> m () #

Generalized version of `cancelWith`.

asyncThreadId :: Async a -> ThreadId #

Returns the `ThreadId` of the thread running the given `Async`.

data AsyncCancelled #

The exception thrown by `cancel` to terminate a thread.

Constructors

AsyncCancelled |

#### Instances

Instances details

Exception AsyncCancelled |
Instance details Defined in Control.Concurrent.Async.Internal Methods toException :: AsyncCancelled -> SomeException # fromException :: SomeException -> Maybe AsyncCancelled # displayException :: AsyncCancelled -> String # backtraceDesired :: AsyncCancelled -> Bool #
Show AsyncCancelled |
Instance details Defined in Control.Concurrent.Async.Internal Methods showsPrec :: Int -> AsyncCancelled -> ShowS # show :: AsyncCancelled -> String # showList :: [AsyncCancelled] -> ShowS #
Eq AsyncCancelled |
Instance details Defined in Control.Concurrent.Async.Internal Methods (==) :: AsyncCancelled -> AsyncCancelled -> Bool # (/=) :: AsyncCancelled -> AsyncCancelled -> Bool #

## STM operations

waitSTM :: Async a -> STM a #

A version of `wait` 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.

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

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

## Waiting for multiple `Async`s

waitAny :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), a) #

Generalized version of `waitAny`.

waitAnyCatch :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), Either SomeException a) #

Generalized version of `waitAnyCatch`.

waitAnyCancel :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), a) #

Generalized version of `waitAnyCancel`.

waitAnyCatchCancel :: MonadBaseControl IO m => [Async (StM m a)] -> m (Async (StM m a), Either SomeException a) #

Generalized version of `waitAnyCatchCancel`.

waitEither :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either a b) #

Generalized version of `waitEither`.

waitEitherCatch :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either (Either SomeException a) (Either SomeException b)) #

Generalized version of `waitEitherCatch`.

waitEitherCancel :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either a b) #

Generalized version of `waitEitherCancel`.

waitEitherCatchCancel :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (Either (Either SomeException a) (Either SomeException b)) #

Generalized version of `waitEitherCatchCancel`.

waitEither_ :: MonadBase IO m => Async a -> Async b -> m () #

Generalized version of `waitEither_`.

NOTE: This function discards the monadic effects besides IO in the forked computation.

waitBoth :: MonadBaseControl IO m => Async (StM m a) -> Async (StM m b) -> m (a, b) #

Generalized version of `waitBoth`.

## Waiting for multiple `Async`s in STM

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

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

Since: async-2.1.0

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

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

Since: async-2.1.0

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

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

Since: async-2.1.0

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: async-2.1.0

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

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

Since: async-2.1.0

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

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

Since: async-2.1.0

## Linking

link :: MonadBase IO m => Async a -> m () #

Generalized version of `link`.

link2 :: MonadBase IO m => Async a -> Async b -> m () #

Generalized version of `link2`.

data ExceptionInLinkedThread #

Constructors

ExceptionInLinkedThread (Async a) SomeException |

#### Instances

Instances details

Exception ExceptionInLinkedThread |
Instance details Defined in Control.Concurrent.Async.Internal Methods toException :: ExceptionInLinkedThread -> SomeException # fromException :: SomeException -> Maybe ExceptionInLinkedThread # displayException :: ExceptionInLinkedThread -> String # backtraceDesired :: ExceptionInLinkedThread -> Bool #
Show ExceptionInLinkedThread |
Instance details Defined in Control.Concurrent.Async.Internal Methods showsPrec :: Int -> ExceptionInLinkedThread -> ShowS # show :: ExceptionInLinkedThread -> String # showList :: [ExceptionInLinkedThread] -> ShowS #

# Convenient utilities

race :: MonadBaseControl IO m => m a -> m b -> m (Either a b) #

Generalized version of `race`.

race_ :: MonadBaseControl IO m => m a -> m b -> m () #

Generalized version of `race_`.

NOTE: This function discards the monadic effects besides IO in the forked computation.

concurrently :: MonadBaseControl IO m => m a -> m b -> m (a, b) #

Generalized version of `concurrently`.

concurrently_ :: MonadBaseControl IO m => m a -> m b -> m () #

Generalized version of `concurrently_`.

mapConcurrently :: (Traversable t, MonadBaseControl IO m) => (a -> m b) -> t a -> m (t b) #

Generalized version of `mapConcurrently`.

mapConcurrently_ :: (Foldable t, MonadBaseControl IO m) => (a -> m b) -> t a -> m () #

Generalized version of `mapConcurrently_`.

forConcurrently :: (Traversable t, MonadBaseControl IO m) => t a -> (a -> m b) -> m (t b) #

Generalized version of `forConcurrently`.

forConcurrently_ :: (Foldable t, MonadBaseControl IO m) => t a -> (a -> m b) -> m () #

Generalized version of `forConcurrently_`.

replicateConcurrently :: MonadBaseControl IO m => Int -> m a -> m [a] #

Generalized version of `replicateConcurrently`.

replicateConcurrently_ :: MonadBaseControl IO m => Int -> m a -> m () #

Generalized version of `replicateConcurrently_`.

newtype Concurrently (m :: Type -> Type) a #

Generalized version of `Concurrently`.

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

Calling `runConcurrently` on a value of type ``Concurrently` m a` will execute the IO-based lifted 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 :: m a

#### Instances

Instances details

MonadBaseControl IO m => Alternative (Concurrently m) # |
Instance details Defined in Control.Concurrent.Async.Lifted Methods empty :: Concurrently m a # (<|>) :: Concurrently m a -> Concurrently m a -> Concurrently m a # some :: Concurrently m a -> Concurrently m [a] # many :: Concurrently m a -> Concurrently m [a] #
MonadBaseControl IO m => Applicative (Concurrently m) # |
Instance details Defined in Control.Concurrent.Async.Lifted Methods pure :: a -> Concurrently m a # (<*>) :: Concurrently m (a -> b) -> Concurrently m a -> Concurrently m b # liftA2 :: (a -> b -> c) -> Concurrently m a -> Concurrently m b -> Concurrently m c # (*>) :: Concurrently m a -> Concurrently m b -> Concurrently m b # (<*) :: Concurrently m a -> Concurrently m b -> Concurrently m a #
Functor m => Functor (Concurrently m) # |
Instance details Defined in Control.Concurrent.Async.Lifted Methods fmap :: (a -> b) -> Concurrently m a -> Concurrently m b # (<$) :: a -> Concurrently m b -> Concurrently m a #
(MonadBaseControl IO m, Semigroup a, Monoid a) => Monoid (Concurrently m a) # |
Instance details Defined in Control.Concurrent.Async.Lifted Methods mempty :: Concurrently m a # mappend :: Concurrently m a -> Concurrently m a -> Concurrently m a # mconcat :: [Concurrently m a] -> Concurrently m a #
(MonadBaseControl IO m, Semigroup a) => Semigroup (Concurrently m a) # |
Instance details Defined in Control.Concurrent.Async.Lifted Methods (<>) :: Concurrently m a -> Concurrently m a -> Concurrently m a # sconcat :: NonEmpty (Concurrently m a) -> Concurrently m a # stimes :: Integral b => b -> Concurrently m a -> Concurrently m a #

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

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