-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Run IO operations asynchronously and wait for their results -- -- This package provides a higher-level interface over threads, in which -- an Async a is a concurrent thread that will eventually -- deliver a value of type a. The package provides ways to -- create Async computations, wait for their results, and cancel -- them. -- -- Using Async is safer than using threads in two ways: -- -- @package async @version 2.0.0.0 -- | This module provides a set of operations for running IO operations -- asynchronously and waiting for their results. It is a thin layer over -- the basic concurrency operations provided by -- Control.Concurrent. The main additional functionality it -- provides is the ability to wait for the return value of a thread, but -- the interface also provides some additional safety and robustness over -- using threads and MVar directly. -- -- The basic type is Async a, which represents an -- asynchronous IO action that will return a value of type -- a, or die with an exception. An Async corresponds to -- a thread, and its ThreadId can be obtained with -- asyncThreadId, although that should rarely be necessary. -- -- For example, to fetch two web pages at the same time, we could do this -- (assuming a suitable getURL function): -- -- 
--   do a1 <- async (getURL url1)
--      a2 <- async (getURL url2)
--      page1 <- wait a1
--      page2 <- wait a2
--      ...
--
-- -- where async starts the operation in a separate thread, and -- wait waits for and returns the result. If the operation throws -- an exception, then that exception is re-thrown by wait. This is -- one of the ways in which this library provides some additional safety: -- it is harder to accidentally forget about exceptions thrown in child -- threads. -- -- A slight improvement over the previous example is this: -- -- 
--   withAsync (getURL url1) $ \a1 -> do
--   withAsync (getURL url2) $ \a2 -> do
--   page1 <- wait a1
--   page2 <- wait a2
--   ...
--
-- -- withAsync is like async, except that the Async is -- automatically killed (using cancel) if the enclosing IO -- operation returns before it has completed. Consider the case when the -- first wait throws an exception; then the second Async -- will be automatically killed rather than being left to run in the -- background, possibly indefinitely. This is the second way that the -- library provides additional safety: using withAsync means we -- can avoid accidentally leaving threads running. Furthermore, -- withAsync allows a tree of threads to be built, such that -- children are automatically killed if their parents die for any reason. -- -- The pattern of performing two IO actions concurrently and waiting for -- their results is packaged up in a combinator concurrently, so -- we can further shorten the above example to: -- -- 
--   (page1, page2) <- concurrently (getURL url1) (getURL url2)
--   ...
--
module Control.Concurrent.Async -- | 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). data Async a -- | Spawn an asynchronous action in a separate thread. async :: IO a -> IO (Async a) -- | 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, cancel is called on the -- Async. -- -- 
--   withAsync action inner = bracket (async action) cancel inner
--
-- -- This is a useful variant of async that ensures an -- Async is never left running unintentionally. -- -- Since cancel may block, withAsync may also block; see -- cancel for details. withAsync :: IO a -> (Async a -> IO b) -> IO b -- | Returns the ThreadId of the thread running the given -- Async. asyncThreadId :: Async a -> ThreadId -- | 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
--
wait :: Async a -> IO 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
--
poll :: Async a -> IO (Maybe (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
--
waitCatch :: Async a -> IO (Either SomeException a) -- | Cancel an asynchronous action by throwing the ThreadKilled -- exception to it. Has no effect if the Async has already -- completed. -- -- 
--   cancel a = throwTo (asyncThreadId a) ThreadKilled
--
-- -- Note that cancel is synchronous in the same sense as -- throwTo. It does not return until the exception has been thrown -- in the target thread, or the target thread has completed. In -- particular, if the target thread is making a foreign call, the -- exception will not be thrown until the foreign call returns, and in -- this case cancel may block indefinitely. An asynchronous -- cancel can of course be obtained by wrapping cancel -- itself in async. cancel :: Async a -> 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. cancelWith :: Exception e => Async a -> e -> IO () -- | A version of wait that can be used inside an STM transaction. waitSTM :: Async a -> STM a -- | A version of poll that can be used inside an STM transaction. pollSTM :: Async a -> STM (Maybe (Either SomeException a)) -- | A version of waitCatch that can be used inside an STM -- transaction. waitCatchSTM :: Async a -> STM (Either SomeException 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. -- -- If multiple Asyncs complete or have completed, then the value -- returned corresponds to the first completed Async in the list. waitAny :: [Async a] -> IO (Async a, 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. -- -- If multiple Asyncs complete or have completed, then the value -- returned corresponds to the first completed Async in the list. waitAnyCatch :: [Async a] -> IO (Async a, Either SomeException a) -- | Like waitAny, but also cancels the other asynchronous -- operations as soon as one has completed. waitAnyCancel :: [Async a] -> IO (Async a, a) -- | Like waitAnyCatch, but also cancels the other asynchronous -- operations as soon as one has completed. waitAnyCatchCancel :: [Async a] -> IO (Async a, Either SomeException a) -- | 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. waitEither :: Async a -> Async b -> IO (Either a b) -- | Wait for the first of two Asyncs to finish. waitEitherCatch :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b)) -- | Like waitEither, but also cancels both Asyncs -- before returning. waitEitherCancel :: Async a -> Async b -> IO (Either a b) -- | Like waitEitherCatch, but also cancels both -- Asyncs before returning. waitEitherCatchCancel :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b)) -- | Like waitEither, but the result is ignored. waitEither_ :: Async a -> Async b -> IO () -- | 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. waitBoth :: Async a -> Async b -> IO (a, b) -- | 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. link :: Async a -> IO () -- | Link two Asyncs together, such that if either raises an -- exception, the same exception is re-thrown in the other -- Async. link2 :: Async a -> Async b -> IO () -- | 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 (Either a b) -- | Like race, but the result is ignored. race_ :: IO a -> IO b -> IO () -- | 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
--
concurrently :: IO a -> IO b -> IO (a, b) instance Ord (Async a) instance Eq (Async a)