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

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

Control.Concurrent.Async.Lifted.Safe

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 safe variant of `Control.Concurrent.Async.Lifted`.

This module assumes your monad stack to satisfy ``StM` m a ~ a` so you can't mess up monadic effects. If your monad stack is stateful, use `Control.Concurrent.Async.Lifted` with special care.

Synopsis

- data Async a :: * -> *
- class StM m a ~ a => Pure m a
- type family Forall k (p :: k -> Constraint) :: Constraint
- async :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a)
- asyncBound :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a)
- asyncOn :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m (Async a)
- asyncWithUnmask :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => ((forall b. m b -> m b) -> m a) -> m (Async a)
- asyncOnWithUnmask :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => Int -> ((forall b. m b -> m b) -> m a) -> m (Async a)
- withAsync :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b
- withAsyncBound :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b
- withAsyncOn :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> (Async a -> m b) -> m b
- withAsyncWithUnmask :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => ((forall c. m c -> m c) -> m a) -> (Async a -> m b) -> m b
- withAsyncOnWithUnmask :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Int -> ((forall c. m c -> m c) -> m a) -> (Async a -> m b) -> m b
- wait :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m a
- poll :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m (Maybe (Either SomeException a))
- waitCatch :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m (Either SomeException a)
- cancel :: MonadBase IO m => Async a -> m ()
- cancelWith :: (MonadBase IO m, Exception e) => Async a -> e -> m ()
- asyncThreadId :: Async a -> ThreadId
- waitSTM :: Async a -> STM a
- pollSTM :: Async a -> STM (Maybe (Either SomeException a))
- waitCatchSTM :: Async a -> STM (Either SomeException a)
- waitAny :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatch :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitAnyCancel :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatchCancel :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitEither :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatch :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
- waitEitherCancel :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatchCancel :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
- waitEither_ :: MonadBase IO m => Async a -> Async b -> m ()
- waitBoth :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async 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 ()
- race :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (Either a b)
- race_ :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m ()
- concurrently :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (a, b)
- mapConcurrently :: (Traversable t, MonadBaseControl IO m, Forall (Pure m)) => (a -> m b) -> t a -> m (t b)
- mapConcurrently_ :: (Foldable t, MonadBaseControl IO m, Forall (Pure m)) => (a -> m b) -> t a -> m ()
- forConcurrently :: (Traversable t, MonadBaseControl IO m, Forall (Pure m)) => t a -> (a -> m b) -> m (t b)
- forConcurrently_ :: (Foldable t, MonadBaseControl IO m, Forall (Pure m)) => t a -> (a -> m b) -> m ()
- data Concurrently m a where
  - Concurrently :: Forall (Pure m) => {..} -> Concurrently m a

# 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

Functor Async |
Methods fmap :: (a -> b) -> Async a -> Async b # (<$) :: a -> Async b -> Async a #
Eq (Async a) |
Methods (==) :: Async a -> Async a -> Bool # (/=) :: Async a -> Async a -> Bool #
Ord (Async a) |
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 #

class StM m a ~ a => Pure m a #

Most of the functions in this module have ``Forall` (`Pure` m)` in their constraints, which means they require the monad `m` satisfies ``StM` m a ~ a` for all `a`.

Instances

(~) * (StM m a) a => Pure m a # |

type family Forall k (p :: k -> Constraint) :: Constraint #

A representation of the quantified constraint `forall a. p a`.

Instances

type Forall k p |
type Forall k p = Forall_ k p

## Spawning

async :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a) #

Generalized version of `async`.

asyncBound :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a) #

Generalized version of `asyncBound`.

asyncOn :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m (Async a) #

Generalized version of `asyncOn`.

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

Generalized version of `asyncWithUnmask`.

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

Generalized version of `asyncOnWithUnmask`.

## Spawning with automatic `cancel`ation

withAsync :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b #

Generalized version of `withAsync`.

withAsyncBound :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b #

Generalized version of `withAsyncBound`.

withAsyncOn :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> (Async a -> m b) -> m b #

Generalized version of `withAsyncOn`.

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

Generalized version of `withAsyncWithUnmask`.

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

Generalized version of `withAsyncOnWithUnmask`.

## Quering `Async`s

wait :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m a #

Generalized version of `wait`.

poll :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m (Maybe (Either SomeException a)) #

Generalized version of `poll`.

waitCatch :: forall m a. (MonadBase IO m, Forall (Pure m)) => Async a -> m (Either SomeException a) #

Generalized version of `waitCatch`.

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

Generalized version of `cancel`.

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

## 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 :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a) #

Generalized version of `waitAny`.

waitAnyCatch :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a) #

Generalized version of `waitAnyCatch`.

waitAnyCancel :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a) #

Generalized version of `waitAnyCancel`.

waitAnyCatchCancel :: forall m a. (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a) #

Generalized version of `waitAnyCatchCancel`.

waitEither :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b) #

Generalized version of `waitEither`.

waitEitherCatch :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b)) #

Generalized version of `waitEitherCatch`.

waitEitherCancel :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b) #

Generalized version of `waitEitherCancel`.

waitEitherCatchCancel :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async 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_`

waitBoth :: forall m a b. (MonadBase IO m, Forall (Pure m)) => Async a -> Async 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: 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: 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: 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: 2.1.0

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

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

Since: 2.1.0

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

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

Since: 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`.

# Convenient utilities

race :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (Either a b) #

Generalized version of `race`.

race_ :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m () #

Generalized version of `race_`.

concurrently :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (a, b) #

Generalized version of `concurrently`.

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

Generalized version of `mapConcurrently`.

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

Generalized version of `mapConcurrently_`.

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

Generalized version of `forConcurrently`.

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

Generalized version of `forConcurrently_`.

data Concurrently m a where #

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 :: Forall (Pure m) => {..} -> Concurrently m a |
Fields runConcurrently :: m a

Instances

Functor m => Functor (Concurrently m) # |
Methods fmap :: (a -> b) -> Concurrently m a -> Concurrently m b # (<$) :: a -> Concurrently m b -> Concurrently m a #
(MonadBaseControl IO m, Forall * (Pure m)) => Applicative (Concurrently m) # |
Methods pure :: a -> Concurrently m a # (<*>) :: Concurrently m (a -> b) -> Concurrently m a -> Concurrently m b # (*>) :: Concurrently m a -> Concurrently m b -> Concurrently m b # (<*) :: Concurrently m a -> Concurrently m b -> Concurrently m a #
(MonadBaseControl IO m, Forall * (Pure m)) => Alternative (Concurrently m) # |
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, Semigroup a, Forall * (Pure m)) => Semigroup (Concurrently m a) # |
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 #
(MonadBaseControl IO m, Semigroup a, Monoid a, Forall * (Pure m)) => Monoid (Concurrently m a) # |
Methods mempty :: Concurrently m a # mappend :: Concurrently m a -> Concurrently m a -> Concurrently m a # mconcat :: [Concurrently m a] -> Concurrently m a #