Control.Concurrent.Async.Lifted.Safe

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.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 :: Type -> Type) a
- class (forall (a :: k). p a) => Forall (p :: k -> Constraint)
- async :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a)
- asyncBound :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m (Async a)
- asyncOn :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m (Async a)
- asyncWithUnmask :: (MonadBaseControl IO m, Forall (Pure m)) => ((forall b. m b -> m b) -> m a) -> m (Async a)
- asyncOnWithUnmask :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> ((forall b. m b -> m b) -> m a) -> m (Async a)
- withAsync :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b
- withAsyncBound :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b
- withAsyncOn :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> (Async a -> m b) -> m b
- withAsyncWithUnmask :: (MonadBaseControl IO m, Forall (Pure m)) => ((forall c. m c -> m c) -> m a) -> (Async a -> m b) -> m b
- withAsyncOnWithUnmask :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> ((forall c. m c -> m c) -> m a) -> (Async a -> m b) -> m b
- wait :: (MonadBase IO m, Forall (Pure m)) => Async a -> m a
- poll :: (MonadBase IO m, Forall (Pure m)) => Async a -> m (Maybe (Either SomeException a))
- waitCatch :: (MonadBase IO m, Forall (Pure m)) => Async 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 :: (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatch :: (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitAnyCancel :: (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatchCancel :: (MonadBase IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitEither :: (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatch :: (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
- waitEitherCancel :: (MonadBase IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatchCancel :: (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 :: (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 ()
- data ExceptionInLinkedThread = ExceptionInLinkedThread (Async a) SomeException
- race :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (Either a b)
- race_ :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m ()
- concurrently :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m (a, b)
- concurrently_ :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> m b -> m ()
- 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 ()
- replicateConcurrently :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m [a]
- replicateConcurrently_ :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m ()
- data Concurrently (m :: Type -> Type) a where
  - Concurrently :: forall (m :: Type -> Type) a. Forall (Pure m) => {..} -> Concurrently 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 #

class StM m a ~ a => Pure (m :: Type -> Type) 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

Instances details

StM m a ~ a => Pure m a # |
Instance details Defined in Control.Concurrent.Async.Lifted.Safe

class (forall (a :: k). p a) => Forall (p :: k -> Constraint) #

#### Instances

Instances details

(forall (a :: k). p a) => Forall (p :: k -> Constraint) |
Instance details Defined in Data.Constraint.Forall

## Spawning

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

Generalized version of `async`.

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

Generalized version of `asyncBound`.

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

Generalized version of `asyncOn`.

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

Generalized version of `asyncWithUnmask`.

asyncOnWithUnmask :: (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 :: (MonadBaseControl IO m, Forall (Pure m)) => m a -> (Async a -> m b) -> m b #

Generalized version of `withAsync`.

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

Generalized version of `withAsyncBound`.

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

Generalized version of `withAsyncOn`.

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

Generalized version of `wait`.

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

Generalized version of `poll`.

waitCatch :: (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`.

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

Generalized version of `waitAny`.

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

Generalized version of `waitAnyCatch`.

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

Generalized version of `waitAnyCancel`.

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

Generalized version of `waitAnyCatchCancel`.

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

Generalized version of `waitEither`.

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

Generalized version of `waitEitherCatch`.

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

Generalized version of `waitEitherCancel`.

waitEitherCatchCancel :: (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 :: (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: 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, Forall (Pure m)) => m a -> m b -> m (Either a b) #

Generalized version of `race`.

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

Generalized version of `race_`.

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

Generalized version of `concurrently`.

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

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

replicateConcurrently :: (MonadBaseControl IO m, Forall (Pure m)) => Int -> m a -> m [a] #

Generalized version of `replicateConcurrently`.

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

Generalized version of `replicateConcurrently_`.

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

#### Instances

Instances details

(MonadBaseControl IO m, Forall (Pure m)) => Alternative (Concurrently m) # |
Instance details Defined in Control.Concurrent.Async.Lifted.Safe 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, Forall (Pure m)) => Applicative (Concurrently m) # |
Instance details Defined in Control.Concurrent.Async.Lifted.Safe 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.Safe Methods fmap :: (a -> b) -> Concurrently m a -> Concurrently m b # (<$) :: a -> Concurrently m b -> Concurrently m a #
(MonadBaseControl IO m, Semigroup a, Monoid a, Forall (Pure m)) => Monoid (Concurrently m a) # |
Instance details Defined in Control.Concurrent.Async.Lifted.Safe 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, Forall (Pure m)) => Semigroup (Concurrently m a) # |
Instance details Defined in Control.Concurrent.Async.Lifted.Safe 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`.