Control.Distributed.Process.Async

This API provides a means for spawning asynchronous operations, waiting for their results, cancelling them and various other utilities. Asynchronous operations can be executed on remote nodes.

Asynchronous Operations

There is an implicit contract for async workers; Workers must exit normally (i.e., should not call the exit, die or terminate Cloud Haskell primitives), otherwise the AsyncResult will end up being AsyncFailed DiedException instead of containing the result.

Portions of this file are derived from the Control.Concurrent.Async module, from the async package written by Simon Marlow.

Exported types

type AsyncRef = ProcessId

A reference to an asynchronous action

data AsyncTask a

A task to be performed asynchronously.

Constructors

AsyncTask

Fields

• asyncTask :: Process a

  the task to be performed

AsyncRemoteTask

Fields

• asyncTaskDict :: Static (SerializableDict a)

  the serializable dict required to spawn a remote process

• asyncTaskNode :: NodeId

  the node on which to spawn the asynchronous task

• asyncTaskProc :: Closure (Process a)

  the task to be performed, wrapped in a closure environment

data Async a

An handle for an asynchronous action spawned by async. Asynchronous operations are run in a separate process, and operations are provided for waiting for asynchronous actions to complete and obtaining their results (see e.g. wait).

Handles of this type cannot cross remote boundaries, nor are they Serializable.

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

data AsyncResult a

Represents the result of an asynchronous action, which can be in one of several states at any given time.

Constructors

AsyncDone a

a completed action and its result

AsyncFailed DiedReason

a failed action and the failure reason

AsyncLinkFailed DiedReason

a link failure and the reason

AsyncCancelled

a cancelled action

AsyncPending

a pending action (that is still running)

Instances

Functor AsyncResult

Methods

fmap :: (a -> b) -> AsyncResult a -> AsyncResult b

(<$) :: a -> AsyncResult b -> AsyncResult a

Eq a => Eq (AsyncResult a)

Methods

(==) :: AsyncResult a -> AsyncResult a -> Bool

(/=) :: AsyncResult a -> AsyncResult a -> Bool

Show a => Show (AsyncResult a)

Methods

showsPrec :: Int -> AsyncResult a -> ShowS

show :: AsyncResult a -> String

showList :: [AsyncResult a] -> ShowS

Generic (AsyncResult a)

Associated Types

type Rep (AsyncResult a) :: * -> *

Methods

from :: AsyncResult a -> Rep (AsyncResult a) x

to :: Rep (AsyncResult a) x -> AsyncResult a

Serializable a => Binary (AsyncResult a)

Methods

put :: AsyncResult a -> Put

get :: Get (AsyncResult a)

putList :: [AsyncResult a] -> Put

type Rep (AsyncResult a)

type Rep (AsyncResult a) = D1 * (MetaData "AsyncResult" "Control.Distributed.Process.Async.Internal.Types" "distributed-process-async-0.2.6-G75ME051tZtIK9teBfjXjZ" False) ((:+:) * ((:+:) * (C1 * (MetaCons "AsyncDone" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * a))) (C1 * (MetaCons "AsyncFailed" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * DiedReason)))) ((:+:) * (C1 * (MetaCons "AsyncLinkFailed" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * DiedReason))) ((:+:) * (C1 * (MetaCons "AsyncCancelled" PrefixI False) (U1 *)) (C1 * (MetaCons "AsyncPending" PrefixI False) (U1 *)))))

Spawning asynchronous operations

async :: Serializable a => AsyncTask a -> Process (Async a)

Spawns an asynchronous action and returns a handle to it, which can be used to obtain its status and/or result or interact with it (using the API exposed by this module).

asyncLinked :: Serializable a => AsyncTask a -> Process (Async a)

This is a useful variant of async that ensures an Async task is never left running unintentionally. We ensure that if the caller's process exits, that the worker is killed.

There is currently a contract for async workers, that they should exit normally (i.e., they should not call the exit or kill with their own ProcessId nor use the terminate primitive to cease functining), otherwise the AsyncResult will end up being AsyncFailed DiedException instead of containing the desired result.

task :: Process a -> AsyncTask a

Wraps a regular Process a as an AsyncTask.

remoteTask :: Static (SerializableDict a) -> NodeId -> Closure (Process a) -> AsyncTask a

Wraps the components required and builds a remote AsyncTask.

monitorAsync :: Async a -> Process MonitorRef

Given an Async handle, monitor the worker process.

asyncWorker :: Async a -> ProcessId

Provides the pid of the worker process performing the async operation.

Cancelling asynchronous operations

cancel :: Async a -> Process ()

Cancel an asynchronous operation.

cancelWait :: Serializable a => Async a -> Process (AsyncResult a)

Cancel an asynchronous operation and wait for the cancellation to complete.

cancelWith :: Serializable b => b -> Async a -> Process ()

Cancel an asynchronous operation immediately.

cancelKill :: String -> Async a -> Process ()

Like cancelWith but sends a kill instruction instead of an exit.

Querying for results

poll :: Serializable a => Async a -> Process (AsyncResult a)

Check whether an Async has completed yet.

check :: Serializable a => Async a -> Process (Maybe (AsyncResult a))

Like poll but returns Nothing if (poll hAsync) == AsyncPending.

wait :: Async a -> Process (AsyncResult a)

Wait for an asynchronous action to complete, and return its value. The result (which can include failure and/or cancellation) is encoded by the AsyncResult type.

wait = liftIO . atomically . waitSTM

waitAny :: Serializable a => [Async a] -> Process (Async a, AsyncResult a)

Wait for any of the supplied Asyncs to complete. If multiple Asyncs complete, then the value returned corresponds to the first completed Async in the list.

NB: Unlike AsyncChan, Async does not discard its AsyncResult once read, therefore the semantics of this function are different to the former. Specifically, if asyncs = [a1, a2, a3] and (AsyncDone _) = a1 then the remaining a2, a3 will never be returned by waitAny.

Waiting with timeouts

waitAnyTimeout :: Serializable a => Int -> [Async a] -> Process (Maybe (AsyncResult a))

Like waitAny but times out after the specified delay.

waitTimeout :: Serializable a => Int -> Async a -> Process (Maybe (AsyncResult a))

Wait for an asynchronous operation to complete or timeout.

waitCancelTimeout :: Serializable a => Int -> Async a -> Process (AsyncResult a)

Wait for an asynchronous operation to complete or timeout. If it times out, then cancelWait the async handle.

waitCheckTimeout :: Serializable a => Int -> Async a -> Process (AsyncResult a)

Wait for an asynchronous operation to complete or timeout.

STM versions

pollSTM :: Async a -> STM (Maybe (AsyncResult a))

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

waitSTM :: Async a -> STM (AsyncResult a)

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

waitAnySTM :: [Async a] -> IO (Async a, AsyncResult a)

STM version of waitAny.

waitAnyCancel :: Serializable a => [Async a] -> Process (Async a, AsyncResult a)

Like waitAny, but also cancels the other asynchronous operations as soon as one has completed.

waitEither :: Async a -> Async b -> Process (Either (AsyncResult a) (AsyncResult b))

Wait for the first of two Asyncs to finish.

waitEither_ :: Async a -> Async b -> Process ()

Like waitEither, but the result is ignored.

waitBoth :: Async a -> Async b -> Process (AsyncResult a, AsyncResult b)

Waits for both Asyncs to finish.