Control.Distributed.Process

Cloud Haskell

This is an implementation of Cloud Haskell, as described in Towards Haskell in the Cloud by Jeff Epstein, Andrew Black, and Simon Peyton Jones (http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/), although some of the details are different. The precise message passing semantics are based on A unified semantics for future Erlang by Hans Svensson, Lars-Åke Fredlund and Clara Benac Earle.

For a detailed description of the package and other reference materials, please see the distributed-process wiki page on github: https://github.com/haskell-distributed/distributed-process/wiki.

Basic types

data ProcessId

Process identifier

Instances

Eq ProcessId

Ord ProcessId

Show ProcessId

Typeable ProcessId

Binary ProcessId

data NodeId

Node identifier

Instances

Eq NodeId

Ord NodeId

Show NodeId

Typeable NodeId

Binary NodeId

data Process a

The Cloud Haskell Process type

Instances

Monad Process

Functor Process

Typeable1 Process

Applicative Process

MonadIO Process

MonadReader LocalProcess Process

data SendPortId

A send port is identified by a SendPortId.

You cannot send directly to a SendPortId; instead, use newChan to create a SendPort.

Instances

Eq SendPortId

Ord SendPortId

Show SendPortId

Binary SendPortId

processNodeId :: ProcessId -> NodeId

The ID of the node the process is running on

sendPortProcessId :: SendPortId -> ProcessId

The ID of the process that will receive messages sent on this port

liftIO :: MonadIO m => forall a. IO a -> m a

Lift a computation from the IO monad.

Basic messaging

send :: Serializable a => ProcessId -> a -> Process ()

Send a message

expect :: forall a. Serializable a => Process a

Wait for a message of a specific type

expectTimeout :: forall a. Serializable a => Int -> Process (Maybe a)

Like expect but with a timeout

Channels

data ReceivePort a

The receive end of a typed channel (not serializable)

Note that ReceivePort implements Functor, Applicative, Alternative and Monad. This is especially useful when merging receive ports.

Instances

Monad ReceivePort

Functor ReceivePort

Typeable1 ReceivePort

Applicative ReceivePort

Alternative ReceivePort

data SendPort a

The send send of a typed channel (serializable)

Instances

Typeable1 SendPort

Eq (SendPort a)

Eq (SendPort a) => Ord (SendPort a)

Show (SendPort a)

Binary (SendPort a)

sendPortId :: SendPort a -> SendPortId

The (unique) ID of this send port

newChan :: Serializable a => Process (SendPort a, ReceivePort a)

Create a new typed channel

sendChan :: Serializable a => SendPort a -> a -> Process ()

Send a message on a typed channel

receiveChan :: Serializable a => ReceivePort a -> Process a

Wait for a message on a typed channel

receiveChanTimeout :: Serializable a => Int -> ReceivePort a -> Process (Maybe a)

Like receiveChan but with a timeout. If the timeout is 0, do a non-blocking check for a message.

mergePortsBiased :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

Merge a list of typed channels.

The result port is left-biased: if there are messages available on more than one port, the first available message is returned.

mergePortsRR :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

Like mergePortsBiased, but with a round-robin scheduler (rather than left-biased)

Advanced messaging

data Match b

Opaque type used in receiveWait and receiveTimeout

receiveWait :: [Match b] -> Process b

Test the matches in order against each message in the queue

receiveTimeout :: Int -> [Match b] -> Process (Maybe b)

Like receiveWait but with a timeout.

If the timeout is zero do a non-blocking check for matching messages. A non-zero timeout is applied only when waiting for incoming messages (that is, after we have checked the messages that are already in the mailbox).

match :: forall a b. Serializable a => (a -> Process b) -> Match b

Match against any message of the right type

matchIf :: forall a b. Serializable a => (a -> Bool) -> (a -> Process b) -> Match b

Match against any message of the right type that satisfies a predicate

matchUnknown :: Process b -> Match b

Remove any message from the queue

data AbstractMessage

Represents a received message and provides two basic operations on it.

Constructors

AbstractMessage

Fields

forward :: ProcessId -> Process ()

forward the message to ProcessId

maybeHandleMessage :: forall a b. Serializable a => (a -> Process b) -> Process (Maybe b)

Handle the message. If the type of the message matches the type of the first argument to the supplied expression, then the expression will be evaluated against it. If this runtime type checking fails, then Nothing will be returned to indicate the fact. If the check succeeds and evaluation proceeds however, the resulting value with be wrapped with Just.

matchAny :: forall b. (AbstractMessage -> Process b) -> Match b

Match against an arbitrary message. matchAny removes the first available message from the process mailbox, and via the AbstractMessage type, supports forwarding or handling the message if it is of the correct type. If not of the right type, then the AbstractMessage maybeHandleMessage function will not evaluate the supplied expression, but the message will still have been removed from the process mailbox!

matchAnyIf :: forall a b. Serializable a => (a -> Bool) -> (AbstractMessage -> Process b) -> Match b

Match against an arbitrary message. matchAnyIf will only remove the message from the process mailbox, if the supplied condition matches. The success (or failure) of runtime type checks in maybeHandleMessage does not count here, i.e., if the condition evaluates to True then the message will be removed from the process mailbox and decoded, but that does not guarantee that an expression passed to maybeHandleMessage will pass the runtime type checks and therefore be evaluated. If the types do not match up, then maybeHandleMessage returns Nothing.

matchChan :: ReceivePort a -> (a -> Process b) -> Match b

Process management

spawn :: NodeId -> Closure (Process ()) -> Process ProcessId

Spawn a process

For more information about Closure, see Control.Distributed.Process.Closure.

See also call.

call :: Serializable a => Static (SerializableDict a) -> NodeId -> Closure (Process a) -> Process a

Run a process remotely and wait for it to reply

We monitor the remote process: if it dies before it can send a reply, we die too.

For more information about Static, SerializableDict, and Closure, see Control.Distributed.Process.Closure.

See also spawn.

terminate :: Process a

Terminate immediately (throws a ProcessTerminationException)

die :: Serializable a => a -> Process b

Die immediately - throws a ProcessExitException with the given reason.

kill :: ProcessId -> String -> Process ()

Forceful request to kill a process. Where exit provides an exception that can be caught and handled, kill throws an unexposed exception type which cannot be handled explicitly (by type).

exit :: Serializable a => ProcessId -> a -> Process ()

Graceful request to exit a process. Throws ProcessExitException with the supplied reason encoded as a message. Any exit signal raised in this manner can be handled using the catchExit family of functions.

catchExit :: forall a b. (Show a, Serializable a) => Process b -> (ProcessId -> a -> Process b) -> Process b

Catches ProcessExitException. The handler will not be applied unless its type matches the encoded data stored in the exception (see the reason argument given to the exit primitive). If the handler cannot be applied, the exception will be re-thrown.

To handle ProcessExitException without regard for reason, see catch. To handle multiple reasons of differing types, see catchesExit.

catchesExit :: Process b -> [ProcessId -> AbstractMessage -> Process (Maybe b)] -> Process b

Lift catches (almost).

As ProcessExitException stores the exit reason as a typed, encoded message, a handler must accept an input of the expected type. In order to handle a list of potentially different handlers (and therefore input types), a handler passed to catchesExit must accept AbstractMessage and return Maybe (i.e., Just p if it handled the exit reason, otherwise Nothing).

See maybeHandleMessage and AsbtractMessage for more details.

data ProcessTerminationException

Thrown by terminate

Constructors

ProcessTerminationException

Instances

Show ProcessTerminationException

Typeable ProcessTerminationException

Exception ProcessTerminationException

data ProcessRegistrationException

Exception thrown when a process attempts to register a process under an already-registered name or to unregister a name that hasn't been registered

Constructors

ProcessRegistrationException !String

Instances

Show ProcessRegistrationException

Typeable ProcessRegistrationException

Exception ProcessRegistrationException

data SpawnRef

SpawnRef are used to return pids of spawned processes

Instances

Eq SpawnRef

Show SpawnRef

Typeable SpawnRef

Binary SpawnRef

getSelfPid :: Process ProcessId

Our own process ID

getSelfNode :: Process NodeId

Get the node ID of our local node

data ProcessInfo

Provide information about a running process

Constructors

ProcessInfo

Fields

infoNode :: NodeId

infoRegisteredNames :: [String]

infoMessageQueueLength :: Maybe Int

infoMonitors :: [(ProcessId, MonitorRef)]

infoLinks :: [ProcessId]

Instances

Eq ProcessInfo

Show ProcessInfo

Typeable ProcessInfo

Binary ProcessInfo

getProcessInfo :: ProcessId -> Process (Maybe ProcessInfo)

Get information about the specified process

Monitoring and linking

link :: ProcessId -> Process ()

Link to a remote process (asynchronous)

When process A links to process B (that is, process A calls link pidB) then an asynchronous exception will be thrown to process A when process B terminates (normally or abnormally), or when process A gets disconnected from process B. Although it is technically possible to catch these exceptions, chances are if you find yourself trying to do so you should probably be using monitor rather than link. In particular, code such as

 link pidB   -- Link to process B
 expect      -- Wait for a message from process B
 unlink pidB -- Unlink again

doesn't quite do what one might expect: if process B sends a message to process A, and subsequently terminates, then process A might or might not be terminated too, depending on whether the exception is thrown before or after the unlink (i.e., this code has a race condition).

Linking is all-or-nothing: A is either linked to B, or it's not. A second call to link has no effect.

Note that link provides unidirectional linking (see spawnSupervised). Linking makes no distinction between normal and abnormal termination of the remote process.

linkNode :: NodeId -> Process ()

Link to a node (asynchronous)

linkPort :: SendPort a -> Process ()

Link to a channel (asynchronous)

unlink :: ProcessId -> Process ()

Remove a link

This is synchronous in the sense that once it returns you are guaranteed that no exception will be raised if the remote process dies. However, it is asynchronous in the sense that we do not wait for a response from the remote node.

unlinkNode :: NodeId -> Process ()

Remove a node link

This has the same synchronous/asynchronous nature as unlink.

unlinkPort :: SendPort a -> Process ()

Remove a channel (send port) link

This has the same synchronous/asynchronous nature as unlink.

monitor :: ProcessId -> Process MonitorRef

Monitor another process (asynchronous)

When process A monitors process B (that is, process A calls monitor pidB) then process A will receive a ProcessMonitorNotification when process B terminates (normally or abnormally), or when process A gets disconnected from process B. You receive this message like any other (using expect); the notification includes a reason (DiedNormal, DiedException, DiedDisconnect, etc.).

Every call to monitor returns a new monitor reference MonitorRef; if multiple monitors are set up, multiple notifications will be delivered and monitors can be disabled individually using unmonitor.

monitorNode :: NodeId -> Process MonitorRef

Monitor a node (asynchronous)

monitorPort :: forall a. Serializable a => SendPort a -> Process MonitorRef

Monitor a typed channel (asynchronous)

unmonitor :: MonitorRef -> Process ()

Remove a monitor

This has the same synchronous/asynchronous nature as unlink.

withMonitor :: ProcessId -> Process a -> Process a

Establishes temporary monitoring of another process.

withMonitor pid code sets up monitoring of pid for the duration of code. Note: although monitoring is no longer active when withMonitor returns, there might still be unreceived monitor messages in the queue.

data MonitorRef

MonitorRef is opaque for regular Cloud Haskell processes

Instances

Eq MonitorRef

Ord MonitorRef

Show MonitorRef

Binary MonitorRef

data ProcessLinkException

Exceptions thrown when a linked process dies

Constructors

ProcessLinkException !ProcessId !DiedReason

Instances

Show ProcessLinkException

Typeable ProcessLinkException

Exception ProcessLinkException

data NodeLinkException

Exception thrown when a linked node dies

Constructors

NodeLinkException !NodeId !DiedReason

Instances

Show NodeLinkException

Typeable NodeLinkException

Exception NodeLinkException

data PortLinkException

Exception thrown when a linked channel (port) dies

Constructors

PortLinkException !SendPortId !DiedReason

Instances

Show PortLinkException

Typeable PortLinkException

Exception PortLinkException

data ProcessMonitorNotification

Message sent by process monitors

Constructors

ProcessMonitorNotification !MonitorRef !ProcessId !DiedReason

Instances

Show ProcessMonitorNotification

Typeable ProcessMonitorNotification

Binary ProcessMonitorNotification

data NodeMonitorNotification

Message sent by node monitors

Constructors

NodeMonitorNotification !MonitorRef !NodeId !DiedReason

Instances

Show NodeMonitorNotification

Typeable NodeMonitorNotification

Binary NodeMonitorNotification

data PortMonitorNotification

Message sent by channel (port) monitors

Constructors

PortMonitorNotification !MonitorRef !SendPortId !DiedReason

Instances

Show PortMonitorNotification

Typeable PortMonitorNotification

Binary PortMonitorNotification

data DiedReason

Why did a process die?

Constructors

DiedNormal

Normal termination

DiedException !String

The process exited with an exception (provided as String because Exception does not implement Binary)

DiedDisconnect

We got disconnected from the process node

DiedNodeDown

The process node died

DiedUnknownId

Invalid (processnodechannel) identifier

Instances

Eq DiedReason

Show DiedReason

Binary DiedReason

Closures

data Closure a

A closure is a static value and an encoded environment

Instances

Typeable1 Closure

Show (Closure a)

Typeable a => Binary (Closure a)

closure

Arguments

:: Static (ByteString -> a)

Decoder

-> ByteString

Encoded closure environment

-> Closure a

data Static a

A static value. Static is opaque; see staticLabel and staticApply.

Instances

Typeable1 Static

Show (Static a)

Typeable a => Binary (Static a)

unStatic :: Typeable a => Static a -> Process a

Resolve a static value

unClosure :: Typeable a => Closure a -> Process a

Resolve a closure

data RemoteTable

Runtime dictionary for unstatic lookups

Logging

say :: String -> Process ()

Log a string

say message sends a message (time, pid of the current process, message) to the process registered as logger. By default, this process simply sends the string to stderr. Individual Cloud Haskell backends might replace this with a different logger process, however.

Registry

register :: String -> ProcessId -> Process ()

Register a process with the local registry (asynchronous). This version will wait until a response is gotten from the management process. The name must not already be registered. The process need not be on this node. A bad registration will result in a ProcessRegistrationException

The process to be registered does not have to be local itself.

reregister :: String -> ProcessId -> Process ()

Like register, but will replace an existing registration. The name must already be registered.

unregister :: String -> Process ()

Remove a process from the local registry (asynchronous). This version will wait until a response is gotten from the management process. The name must already be registered.

whereis :: String -> Process (Maybe ProcessId)

Query the local process registry

nsend :: Serializable a => String -> a -> Process ()

Named send to a process in the local registry (asynchronous)

registerRemoteAsync :: NodeId -> String -> ProcessId -> Process ()

Register a process with a remote registry (asynchronous).

The process to be registered does not have to live on the same remote node. Reply wil come in the form of a RegisterReply message

See comments in whereisRemoteAsync

reregisterRemoteAsync :: NodeId -> String -> ProcessId -> Process ()

unregisterRemoteAsync :: NodeId -> String -> Process ()

Remove a process from a remote registry (asynchronous).

Reply wil come in the form of a RegisterReply message

See comments in whereisRemoteAsync

whereisRemoteAsync :: NodeId -> String -> Process ()

Query a remote process registry (asynchronous)

Reply will come in the form of a WhereIsReply message.

There is currently no synchronous version of whereisRemoteAsync: if you implement one yourself, be sure to take into account that the remote node might die or get disconnect before it can respond (i.e. you should use monitorNode and take appropriate action when you receive a NodeMonitorNotification).

nsendRemote :: Serializable a => NodeId -> String -> a -> Process ()

Named send to a process in a remote registry (asynchronous)

data WhereIsReply

(Asynchronous) reply from whereis

Constructors

WhereIsReply String (Maybe ProcessId)

Instances

Show WhereIsReply

Typeable WhereIsReply

Binary WhereIsReply

data RegisterReply

(Asynchronous) reply from register and unregister

Constructors

RegisterReply String Bool

Instances

Show RegisterReply

Typeable RegisterReply

Binary RegisterReply

Exception handling

catch :: Exception e => Process a -> (e -> Process a) -> Process a

Lift catch

data Handler a

You need this when using catches

Constructors

forall e . Exception e => Handler (e -> Process a)

Instances

Functor Handler

catches :: Process a -> [Handler a] -> Process a

Lift catches

try :: Exception e => Process a -> Process (Either e a)

Lift try

mask :: ((forall a. Process a -> Process a) -> Process b) -> Process b

Lift mask

onException :: Process a -> Process b -> Process a

Lift onException

bracket :: Process a -> (a -> Process b) -> (a -> Process c) -> Process c

Lift bracket

bracket_ :: Process a -> Process b -> Process c -> Process c

Lift bracket_

finally :: Process a -> Process b -> Process a

Lift finally

Auxiliary API

spawnAsync :: NodeId -> Closure (Process ()) -> Process SpawnRef

Asynchronous version of spawn

(spawn is defined in terms of spawnAsync and expect)

spawnSupervised :: NodeId -> Closure (Process ()) -> Process (ProcessId, MonitorRef)

Spawn a child process, have the child link to the parent and the parent monitor the child

spawnLink :: NodeId -> Closure (Process ()) -> Process ProcessId

Spawn a process and link to it

Note that this is just the sequential composition of spawn and link. (The Unified semantics that underlies Cloud Haskell does not even support a synchronous link operation)

spawnMonitor :: NodeId -> Closure (Process ()) -> Process (ProcessId, MonitorRef)

Like spawnLink, but monitor the spawned process

spawnChannel :: forall a. Typeable a => Static (SerializableDict a) -> NodeId -> Closure (ReceivePort a -> Process ()) -> Process (SendPort a)

Spawn a new process, supplying it with a new ReceivePort and return the corresponding SendPort.

data DidSpawn

(Asynchronius) reply from spawn

Constructors

DidSpawn SpawnRef ProcessId

Instances

Show DidSpawn

Typeable DidSpawn

Binary DidSpawn

Local versions of spawn

spawnLocal :: Process () -> Process ProcessId

Spawn a process on the local node

spawnChannelLocal :: Serializable a => (ReceivePort a -> Process ()) -> Process (SendPort a)

Create a new typed channel, spawn a process on the local node, passing it the receive port, and return the send port

Reconnecting

reconnect :: ProcessId -> Process ()

Cloud Haskell provides the illusion of connection-less, reliable, ordered message passing. However, when network connections get disrupted this illusion cannot always be maintained. Once a network connection breaks (even temporarily) no further communication on that connection will be possible. For example, if process A sends a message to process B, and A is then notified (by monitor notification) that it got disconnected from B, A will not be able to send any further messages to B, unless A explicitly indicates that it is acceptable to attempt to reconnect to B using the Cloud Haskell reconnect primitive.

Importantly, when A calls reconnect it acknowledges that some messages to B might have been lost. For instance, if A sends messages m1 and m2 to B, then receives a monitor notification that its connection to B has been lost, calls reconnect and then sends m3, it is possible that B will receive m1 and m3 but not m2.

Note that reconnect does not mean reconnect now but rather /it is okay to attempt to reconnect on the next send/. In particular, if no further communication attempts are made to B then A can use reconnect to clean up its connection to B.

reconnectPort :: SendPort a -> Process ()

Reconnect to a sendport. See reconnect for more information.