Control.Distributed.Process.Extras

Cloud Haskell Extras

Evaluation Strategies and Support for NFData

When sending messages to a local process (i.e., intra-node), the default approach is to encode (i.e., serialise) the message anyway, just to ensure that no unevaluated thunks are passed to the receiver. In distributed-process, you must explicitly choose to use unsafe primitives that do nothing to ensure evaluation, since this might cause an error in the receiver which would be difficult to debug. Using NFData, it is possible to force evaluation, but there is no way to ensure that both the NFData and Binary instances do so in the same way (i.e., to the same depth, etc) therefore automatic use of NFData is not possible in distributed-process.

By contrast, distributed-process-platform makes extensive use of NFData to force evaluation (and avoid serialisation overheads during intra-node communication), via the NFSerializable type class. This does nothing to fix the potential disparity between NFData and Binary instances, so you should verify that your data is being handled as expected (e.g., by sticking to strict fields, or some such) and bear in mind that things could go wrong.

The UnsafePrimitives module in this library will force evaluation before calling the UnsafePrimitives in distributed-process, which - if you've vetted everything correctly - should provide a bit more safety, whilst still keeping performance at an acceptable level.

Users of the various service and utility models (such as ManagedProcess and the Service and Task APIs) should consult the sub-system specific documentation for instructions on how to utilise these features.

IMPORTANT NOTICE: Despite the apparent safety of forcing evaluation before sending, we still cannot make any actual guarantees about the evaluation semantics of these operations, and therefore the unsafe moniker will remain in place, in one form or another, for all functions and modules that use them.

Addressing/Interaction Tools

The various type classes exposed here, along with some common data types (such as Shutdown, ServerDisconnected, etc.) are intended to simplify your CH programs, and facilitate easily plugging code into higher level libraries such as distributed-process-client-server and distributed-process-supervisor.

Error/Exception Handling

It is important not to be too general when catching exceptions in cloud haskell application, because asynchonous exceptions provide cloud haskell with its process termination mechanism. Two exception types in particular, signal the instigator's intention to stop a process immediately, which are raised (i.e., thrown) in response to the kill and exit primitives provided by the base distributed-process package.

You should generally try to keep exception handling code to the lowest (i.e., most specific) scope possible. If you wish to trap exit signals, use the various flavours of catchExit primitive from distributed-process.

Exported Types

class (Resolvable a, Routable a) => Addressable a

Instances

Addressable ProcessId

class Resolvable a where

Class of things that can be resolved to a ProcessId.

Minimal complete definition

resolve

Methods

resolve :: a -> Process (Maybe ProcessId)

Resolve the reference to a process id, or Nothing if resolution fails

unresolvableMessage :: Resolvable a => a -> String

Unresolvable Addressable Message

Instances

Resolvable String

Methods

resolve :: String -> Process (Maybe ProcessId)

unresolvableMessage :: String -> String

Resolvable ProcessId

Methods

resolve :: ProcessId -> Process (Maybe ProcessId)

unresolvableMessage :: ProcessId -> String

Resolvable Recipient

Methods

resolve :: Recipient -> Process (Maybe ProcessId)

unresolvableMessage :: Recipient -> String

Resolvable LogClient

Methods

resolve :: LogClient -> Process (Maybe ProcessId)

unresolvableMessage :: LogClient -> String

Resolvable (NodeId, String)

Methods

resolve :: (NodeId, String) -> Process (Maybe ProcessId)

unresolvableMessage :: (NodeId, String) -> String

class Routable a where

Class of things that you can route/send serializable message to

Methods

sendTo :: (Serializable m, Resolvable a) => a -> m -> Process ()

Send a message to the target asynchronously

unsafeSendTo :: (NFSerializable m, Resolvable a) => a -> m -> Process ()

Send some NFData message to the target asynchronously, forcing evaluation (i.e., deepseq) beforehand.

Instances

Routable String

Methods

sendTo :: (Serializable m, Resolvable String) => String -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable String) => String -> m -> Process ()

Routable ProcessId

Methods

sendTo :: (Serializable m, Resolvable ProcessId) => ProcessId -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable ProcessId) => ProcessId -> m -> Process ()

Routable Recipient

Methods

sendTo :: (Serializable m, Resolvable Recipient) => Recipient -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable Recipient) => Recipient -> m -> Process ()

Routable LogClient

Methods

sendTo :: (Serializable m, Resolvable LogClient) => LogClient -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable LogClient) => LogClient -> m -> Process ()

Routable LogChan

Methods

sendTo :: (Serializable m, Resolvable LogChan) => LogChan -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable LogChan) => LogChan -> m -> Process ()

Routable (Message -> Process ())

Methods

sendTo :: (Serializable m, Resolvable (Message -> Process ())) => (Message -> Process ()) -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable (Message -> Process ())) => (Message -> Process ()) -> m -> Process ()

Routable (NodeId, String)

Methods

sendTo :: (Serializable m, Resolvable (NodeId, String)) => (NodeId, String) -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable (NodeId, String)) => (NodeId, String) -> m -> Process ()

class Linkable a where

Class of things to which a Process can link itself.

Methods

linkTo :: Resolvable a => a -> Process ()

Create a link with the supplied object.

class Killable p where

Class of things that can be killed (or instructed to exit).

Methods

killProc :: Resolvable p => p -> String -> Process ()

Kill (instruct to exit) generic process, using kill primitive.

exitProc :: (Resolvable p, Serializable m) => p -> m -> Process ()

Kill (instruct to exit) generic process, using exit primitive.

Instances

Resolvable p => Killable p

Methods

killProc :: p -> String -> Process ()

exitProc :: (Resolvable p, Serializable m) => p -> m -> Process ()

class Monitored a r m | a r -> m where

Minimal complete definition

mkMonitor, checkMonitor

Methods

mkMonitor :: a -> Process r

checkMonitor :: a -> r -> m -> Process Bool

Instances

Resolvable a => Monitored a MonitorRef ProcessMonitorNotification

Methods

mkMonitor :: a -> Process MonitorRef

checkMonitor :: a -> MonitorRef -> ProcessMonitorNotification -> Process Bool

class (NFData a, Serializable a) => NFSerializable a

Introduces a class that brings NFData into scope along with Serializable, such that we can force evaluation. Intended for use with the UnsafePrimitives module (which wraps Control.Distributed.Process.UnsafePrimitives), and guarantees evaluatedness in terms of NFData. Please note that we cannot guarantee that an NFData instance will behave the same way as a Binary one with regards evaluation, so it is still possible to introduce unexpected behaviour by using unsafe primitives in this way.

Instances

(NFData a, Serializable a) => NFSerializable a

NFSerializable a => NFSerializable (SendPort a)

data Recipient

A simple means of mapping to a receiver.

Constructors

Pid !ProcessId

Registered !String

RemoteRegistered !String !NodeId

Instances

Eq Recipient

Methods

(==) :: Recipient -> Recipient -> Bool

(/=) :: Recipient -> Recipient -> Bool

Show Recipient

Methods

showsPrec :: Int -> Recipient -> ShowS

show :: Recipient -> String

showList :: [Recipient] -> ShowS

Generic Recipient

Associated Types

type Rep Recipient :: * -> *

Methods

from :: Recipient -> Rep Recipient x

to :: Rep Recipient x -> Recipient

Binary Recipient

Methods

put :: Recipient -> Put

get :: Get Recipient

putList :: [Recipient] -> Put

NFData Recipient

Methods

rnf :: Recipient -> ()

Routable Recipient

Methods

sendTo :: (Serializable m, Resolvable Recipient) => Recipient -> m -> Process ()

unsafeSendTo :: (NFSerializable m, Resolvable Recipient) => Recipient -> m -> Process ()

Resolvable Recipient

Methods

resolve :: Recipient -> Process (Maybe ProcessId)

unresolvableMessage :: Recipient -> String

type Rep Recipient

type Rep Recipient = D1 * (MetaData "Recipient" "Control.Distributed.Process.Extras.Internal.Types" "distributed-process-extras-0.3.5-7qzKH0dWmcLBNm6JMkdrjz" False) ((:+:) * (C1 * (MetaCons "Pid" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * ProcessId))) ((:+:) * (C1 * (MetaCons "Registered" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * String))) (C1 * (MetaCons "RemoteRegistered" PrefixI False) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * String)) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * NodeId))))))

data Shutdown

A ubiquitous shutdown signal that can be used to maintain a consistent shutdown/stop protocol for any process that wishes to handle it.

Constructors

Shutdown

Instances

Eq Shutdown

Methods

(==) :: Shutdown -> Shutdown -> Bool

(/=) :: Shutdown -> Shutdown -> Bool

Show Shutdown

Methods

showsPrec :: Int -> Shutdown -> ShowS

show :: Shutdown -> String

showList :: [Shutdown] -> ShowS

Generic Shutdown

Associated Types

type Rep Shutdown :: * -> *

Methods

from :: Shutdown -> Rep Shutdown x

to :: Rep Shutdown x -> Shutdown

Binary Shutdown

Methods

put :: Shutdown -> Put

get :: Get Shutdown

putList :: [Shutdown] -> Put

NFData Shutdown

Methods

rnf :: Shutdown -> ()

type Rep Shutdown

type Rep Shutdown = D1 * (MetaData "Shutdown" "Control.Distributed.Process.Extras.Internal.Types" "distributed-process-extras-0.3.5-7qzKH0dWmcLBNm6JMkdrjz" False) (C1 * (MetaCons "Shutdown" PrefixI False) (U1 *))

data ExitReason

Provides a reason for process termination.

Constructors

ExitNormal

indicates normal exit

ExitShutdown

normal response to a Shutdown

ExitOther !String

abnormal (error) shutdown

Instances

Eq ExitReason

Methods

(==) :: ExitReason -> ExitReason -> Bool

(/=) :: ExitReason -> ExitReason -> Bool

Show ExitReason

Methods

showsPrec :: Int -> ExitReason -> ShowS

show :: ExitReason -> String

showList :: [ExitReason] -> ShowS

Generic ExitReason

Associated Types

type Rep ExitReason :: * -> *

Methods

from :: ExitReason -> Rep ExitReason x

to :: Rep ExitReason x -> ExitReason

Binary ExitReason

Methods

put :: ExitReason -> Put

get :: Get ExitReason

putList :: [ExitReason] -> Put

NFData ExitReason

Methods

rnf :: ExitReason -> ()

type Rep ExitReason

type Rep ExitReason = D1 * (MetaData "ExitReason" "Control.Distributed.Process.Extras.Internal.Types" "distributed-process-extras-0.3.5-7qzKH0dWmcLBNm6JMkdrjz" False) ((:+:) * (C1 * (MetaCons "ExitNormal" PrefixI False) (U1 *)) ((:+:) * (C1 * (MetaCons "ExitShutdown" PrefixI False) (U1 *)) (C1 * (MetaCons "ExitOther" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * String)))))

data CancelWait

Wait cancellation message.

Constructors

CancelWait

Instances

Eq CancelWait

Methods

(==) :: CancelWait -> CancelWait -> Bool

(/=) :: CancelWait -> CancelWait -> Bool

Show CancelWait

Methods

showsPrec :: Int -> CancelWait -> ShowS

show :: CancelWait -> String

showList :: [CancelWait] -> ShowS

Generic CancelWait

Associated Types

type Rep CancelWait :: * -> *

Methods

from :: CancelWait -> Rep CancelWait x

to :: Rep CancelWait x -> CancelWait

Binary CancelWait

Methods

put :: CancelWait -> Put

get :: Get CancelWait

putList :: [CancelWait] -> Put

NFData CancelWait

Methods

rnf :: CancelWait -> ()

type Rep CancelWait

type Rep CancelWait = D1 * (MetaData "CancelWait" "Control.Distributed.Process.Extras.Internal.Types" "distributed-process-extras-0.3.5-7qzKH0dWmcLBNm6JMkdrjz" False) (C1 * (MetaCons "CancelWait" PrefixI False) (U1 *))

newtype ServerDisconnected

Given when a server is unobtainable.

Constructors

ServerDisconnected DiedReason

Instances

Generic ServerDisconnected

Associated Types

type Rep ServerDisconnected :: * -> *

Methods

from :: ServerDisconnected -> Rep ServerDisconnected x

to :: Rep ServerDisconnected x -> ServerDisconnected

Binary ServerDisconnected

Methods

put :: ServerDisconnected -> Put

get :: Get ServerDisconnected

putList :: [ServerDisconnected] -> Put

NFData ServerDisconnected

Methods

rnf :: ServerDisconnected -> ()

type Rep ServerDisconnected

type Rep ServerDisconnected = D1 * (MetaData "ServerDisconnected" "Control.Distributed.Process.Extras.Internal.Types" "distributed-process-extras-0.3.5-7qzKH0dWmcLBNm6JMkdrjz" True) (C1 * (MetaCons "ServerDisconnected" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * DiedReason)))

type Channel a = (SendPort a, ReceivePort a)

Simple representation of a channel.

type Tag = Int

Tags provide uniqueness for messages, so that they can be matched with their response.

type TagPool = MVar Tag

Generates unique Tag for messages and response pairs. Each process that depends, directly or indirectly, on the call mechanisms in Control.Distributed.Process.Global.Call should have at most one TagPool on which to draw unique message tags.

Primitives overriding those in distributed-process

monitor :: Resolvable a => a -> Process (Maybe MonitorRef)

Monitor any Resolvable object.

module Control.Distributed.Process.Extras.UnsafePrimitives

Utilities and Extended Primitives

spawnSignalled :: Process a -> (a -> Process ()) -> Process ProcessId

Spawn a new (local) process. This variant takes an initialisation action and a secondary expression from the result of the initialisation to Process (). The spawn operation synchronises on the completion of the before action, such that the calling process is guaranteed to only see the newly spawned ProcessId once the initialisation has successfully completed.

spawnLinkLocal :: Process () -> Process ProcessId

Node local version of spawnLink. 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)

spawnMonitorLocal :: Process () -> Process (ProcessId, MonitorRef)

Like spawnLinkLocal, but monitors the spawned process.

linkOnFailure :: ProcessId -> Process ()

CH's link primitive, unlike Erlang's, will trigger when the target process dies for any reason. This function has semantics like Erlang's: it will trigger ProcessLinkException only when the target dies abnormally.

times :: Int -> Process () -> Process ()

Deprecated: use replicateM_ instead

Apply the supplied expression n times

isProcessAlive :: ProcessId -> Process Bool

Check if specified process is alive. Information may be outdated.

matchCond :: Serializable a => (a -> Maybe (Process b)) -> Match b

An alternative to matchIf that allows both predicate and action to be expressed in one parameter.

deliver :: (Addressable a, Serializable m) => m -> a -> Process ()

Send message to Addressable object.

awaitExit :: Resolvable a => a -> Process ()

Wait until Resolvable object will exit. Return immediately if object can't be resolved.

awaitResponse :: Addressable a => a -> [Match (Either ExitReason b)] -> Process (Either ExitReason b)

Safe (i.e., monitored) waiting on an expected response/message.

Call/Tagging support

newTagPool :: Process TagPool

Create a new per-process source of unique message identifiers.

getTag :: TagPool -> Process Tag

Extract a new identifier from a TagPool.

Registration and Process Lookup

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

Returns the pid of the process that has been registered under the given name. This refers to a local, per-node registration, not global registration. If that name is unregistered, a process is started. This is a handy way to start per-node named servers.

whereisOrStartRemote :: NodeId -> String -> Closure (Process ()) -> Process (Maybe ProcessId)

A remote equivalent of whereisOrStart. It deals with the node registry on the given node, and the process, if it needs to be started, will run on that node. If the node is inaccessible, Nothing will be returned.

__remoteTable :: RemoteTable -> RemoteTable