Control.Concurrent.Async.Lifted.Safe

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

Copyright | Copyright (C) 2012-2015 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 Forall p = (p A, p B)
- 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. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> m a
- poll :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> m (Maybe (Either SomeException a))
- waitCatch :: forall m a. (MonadBaseControl 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. (MonadBaseControl IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatch :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitAnyCancel :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => [Async a] -> m (Async a, a)
- waitAnyCatchCancel :: forall m a. (MonadBaseControl IO m, Forall (Pure m)) => [Async a] -> m (Async a, Either SomeException a)
- waitEither :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatch :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
- waitEitherCancel :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)
- waitEitherCatchCancel :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
- waitEither_ :: MonadBaseControl IO m => Async a -> Async b -> m ()
- waitBoth :: forall m a b. (MonadBaseControl 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)
- data Concurrently m a where
  - Concurrently :: Forall (Pure m) => {
    - runConcurrently :: m a
    } -> 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 |
Eq (Async a) |
Ord (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 Forall p = (p A, p B)

A quantified constraint

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

Generalized version of `wait`.

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

Generalized version of `poll`.

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

Generalized version of `waitAny`.

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

Generalized version of `waitAnyCatch`.

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

Generalized version of `waitAnyCancel`.

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

Generalized version of `waitAnyCatchCancel`.

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

Generalized version of `waitEither`.

waitEitherCatch :: forall m a b. (MonadBaseControl 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. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either a b)

Generalized version of `waitEitherCancel`.

waitEitherCatchCancel :: forall m a b. (MonadBaseControl IO m, Forall (Pure m)) => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))

Generalized version of `waitEitherCatchCancel`.

waitEither_ :: MonadBaseControl 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 :: forall m a b. (MonadBaseControl 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`.

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) => m a -> Concurrently m a |
Fields runConcurrently :: m a

Instances

Functor m => Functor (Concurrently m) |
(MonadBaseControl IO m, Forall (Pure m)) => Applicative (Concurrently m) |
(MonadBaseControl IO m, Forall (Pure m)) => Alternative (Concurrently m) |
(MonadBaseControl IO m, Monoid a, Forall (Pure m)) => Monoid (Concurrently m a) |