-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Cloud Haskell Extras
--
-- Supporting library, providing common types and utilities used by the
-- various components that make up the distributed-process-platform
-- package.
@package distributed-process-extras
@version 0.1.0
-- | If you don't know exactly what this module is for and precisely how to
-- use the types within, you should move on, quickly!
module Control.Distributed.Process.Extras.Internal.Unsafe
data PCopy a
-- | Wrap any Typeable datum in a PCopy. We hide the
-- constructor to discourage arbitrary uses of the type, since
-- PCopy is a specialised and potentially dangerous construct.
pCopy :: Typeable a => a -> PCopy a
-- | Matches on PCopy m and returns the m within. This
-- potentially allows us to bypass serialization (and the type
-- constraints it enforces) for local message passing (i.e., with
-- UnencodedMessage data), since PCopy is just a shim.
matchP :: Typeable m => Match (Maybe m)
-- | Matches on a TypedChannel (PCopy a).
matchChanP :: Typeable m => ReceivePort (PCopy m) -> Match m
-- | Given a raw Message, attempt to unwrap a Typeable
-- datum from an enclosing PCopy wrapper.
pUnwrap :: Typeable m => Message -> Process (Maybe m)
-- | A generic input channel that can be read from in the same fashion as a
-- typed channel (i.e., ReceivePort). To read from an input
-- stream in isolation, see readInputStream. To compose an
-- InputStream with reads on a process' mailbox (and/or typed
-- channels), see matchInputStream.
data InputStream a
Null :: InputStream a
-- | Create a new InputStream.
newInputStream :: Typeable a => Either (ReceivePort a) (STM a) -> InputStream a
-- | Constructs a Match for a given InputChannel.
matchInputStream :: InputStream a -> Match a
-- | Read from an InputStream. This is a blocking operation.
readInputStream :: Serializable a => InputStream a -> Process a
data InvalidBinaryShim
InvalidBinaryShim :: InvalidBinaryShim
instance Typeable InvalidBinaryShim
instance Typeable PCopy
instance Typeable InputStream
instance Typeable NullInputStream
instance Show InvalidBinaryShim
instance Eq InvalidBinaryShim
instance Generic (PCopy a)
instance Generic NullInputStream
instance Show NullInputStream
instance Eq NullInputStream
instance Datatype D1PCopy
instance Constructor C1_0PCopy
instance Datatype D1NullInputStream
instance Constructor C1_0NullInputStream
instance NFData NullInputStream
instance Binary NullInputStream
instance Typeable a => Binary (PCopy a)
instance NFData a => NFData (PCopy a)
module Control.Distributed.Process.Extras.Internal.Queue.PriorityQ
newtype PriorityQ k a
PriorityQ :: PQueue k a -> PriorityQ k a
q :: PriorityQ k a -> PQueue k a
empty :: Ord k => PriorityQ k v
isEmpty :: Ord k => PriorityQ k v -> Bool
singleton :: Ord k => k -> a -> PriorityQ k a
enqueue :: Ord k => k -> v -> PriorityQ k v -> PriorityQ k v
dequeue :: Ord k => PriorityQ k v -> Maybe (v, PriorityQ k v)
peek :: Ord k => PriorityQ k v -> Maybe v
-- | A simple FIFO queue implementation backed by Data.Sequence.
module Control.Distributed.Process.Extras.Internal.Queue.SeqQ
data SeqQ a
empty :: SeqQ a
isEmpty :: SeqQ a -> Bool
singleton :: a -> SeqQ a
enqueue :: SeqQ a -> a -> SeqQ a
dequeue :: SeqQ a -> Maybe (a, SeqQ a)
peek :: SeqQ a -> Maybe a
instance Show a => Show (SeqQ a)
instance Eq a => Eq (SeqQ a)
module Control.Distributed.Process.Extras.Internal.Containers.MultiMap
-- | Opaque type of MultiMaps.
data MultiMap k v
-- | Class of things that can be inserted in a map or a set (of mapped
-- values), for which instances of Eq and Hashable must
-- be present.
class (Eq a, Hashable a) => Insertable a
empty :: MultiMap k v
insert :: (Insertable k, Insertable v) => k -> v -> MultiMap k v -> MultiMap k v
member :: Insertable k => k -> MultiMap k a -> Bool
lookup :: Insertable k => k -> MultiMap k v -> Maybe [v]
filter :: Insertable k => (v -> Bool) -> MultiMap k v -> MultiMap k v
filterWithKey :: Insertable k => (k -> v -> Bool) -> MultiMap k v -> MultiMap k v
toList :: MultiMap k v -> [(k, v)]
instance Foldable (MultiMap k)
instance (Eq a, Hashable a) => Insertable a
module Control.Concurrent.Utils
data Lock
class Exclusive a
new :: Exclusive a => IO a
acquire :: (Exclusive a, MonadIO m) => a -> m ()
release :: (Exclusive a, MonadIO m) => a -> m ()
class Synchronised e m where synchronized = synchronised
synchronised :: (Synchronised e m, Exclusive e, Monad m) => e -> m b -> m b
synchronized :: (Synchronised e m, Exclusive e, Monad m) => e -> m b -> m b
withLock :: Exclusive e => e -> IO a -> IO a
instance Synchronised Lock Process
instance Synchronised Lock IO
instance Exclusive Lock
-- | Types used throughout the Extras package
module Control.Distributed.Process.Extras.Internal.Types
-- | Tags provide uniqueness for messages, so that they can be matched with
-- their response.
type Tag = Int
-- | 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.
type TagPool = MVar Tag
-- | Create a new per-process source of unique message identifiers.
newTagPool :: Process TagPool
-- | Extract a new identifier from a TagPool.
getTag :: TagPool -> Process Tag
-- | Class of things to which a Process can link itself.
class Linkable a
linkTo :: Linkable a => a -> Process ()
-- | Class of things that can be killed (or instructed to exit).
class Killable a
killProc :: Killable a => a -> String -> Process ()
exitProc :: (Killable a, Serializable m) => a -> m -> Process ()
-- | Class of things that can be resolved to a ProcessId.
class Resolvable a
resolve :: Resolvable a => a -> Process (Maybe ProcessId)
-- | Provides a unified API for addressing processes.
class Routable a where unresolvableMessage = baseAddressableErrorMessage
sendTo :: (Routable a, Serializable m) => a -> m -> Process ()
unsafeSendTo :: (Routable a, NFSerializable m) => a -> m -> Process ()
unresolvableMessage :: Routable a => a -> String
class (Resolvable a, Routable a) => Addressable a
sendToRecipient :: Serializable m => Recipient -> m -> Process ()
-- | A simple means of mapping to a receiver.
data Recipient
Pid :: !ProcessId -> Recipient
Registered :: !String -> Recipient
RemoteRegistered :: !String -> !NodeId -> Recipient
-- | Used internally in whereisOrStart. Sent as (RegisterSelf,ProcessId).
data RegisterSelf
RegisterSelf :: RegisterSelf
-- | A synchronous version of whereis, this relies on call to
-- perform the relevant monitoring of the remote node.
whereisRemote :: NodeId -> String -> Process (Maybe ProcessId)
-- | resolve the Resolvable or die with specified msg plus details of what
-- didn't resolve
resolveOrDie :: (Routable a, Resolvable a) => a -> String -> Process ProcessId
-- | Wait cancellation message.
data CancelWait
CancelWait :: CancelWait
-- | Simple representation of a channel.
type Channel a = (SendPort a, ReceivePort a)
-- | A ubiquitous shutdown signal that can be used to maintain a
-- consistent shutdown/stop protocol for any process that wishes to
-- handle it.
data Shutdown
Shutdown :: Shutdown
-- | Provides a reason for process termination.
data ExitReason
-- | indicates normal exit
ExitNormal :: ExitReason
-- | normal response to a Shutdown
ExitShutdown :: ExitReason
-- | abnormal (error) shutdown
ExitOther :: !String -> ExitReason
-- | Given when a server is unobtainable.
data ServerDisconnected
ServerDisconnected :: !DiedReason -> ServerDisconnected
-- | 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.
class (NFData a, Serializable a) => NFSerializable a
__remoteTable :: RemoteTable -> RemoteTable
instance [overlap ok] (Resolvable a, Routable a) => Addressable a
instance [overlap ok] Routable (Message -> Process ())
instance [overlap ok] Routable (NodeId, String)
instance [overlap ok] Resolvable (NodeId, String)
instance [overlap ok] Routable String
instance [overlap ok] Resolvable String
instance [overlap ok] Routable ProcessId
instance [overlap ok] Resolvable ProcessId
instance [overlap ok] Routable Recipient
instance [overlap ok] Resolvable Recipient
instance [overlap ok] Resolvable a => Routable a
instance [overlap ok] Resolvable r => Killable r
instance [overlap ok] Killable ProcessId
instance [overlap ok] Typeable CancelWait
instance [overlap ok] Typeable RegisterSelf
instance [overlap ok] Typeable Shutdown
instance [overlap ok] Typeable ExitReason
instance [overlap ok] Typeable Recipient
instance [overlap ok] Typeable ServerDisconnected
instance [overlap ok] Eq CancelWait
instance [overlap ok] Show CancelWait
instance [overlap ok] Generic CancelWait
instance [overlap ok] Generic RegisterSelf
instance [overlap ok] Generic Shutdown
instance [overlap ok] Show Shutdown
instance [overlap ok] Eq Shutdown
instance [overlap ok] Generic ExitReason
instance [overlap ok] Eq ExitReason
instance [overlap ok] Show ExitReason
instance [overlap ok] Generic Recipient
instance [overlap ok] Show Recipient
instance [overlap ok] Eq Recipient
instance [overlap ok] Generic ServerDisconnected
instance Datatype D1CancelWait
instance Constructor C1_0CancelWait
instance Datatype D1RegisterSelf
instance Constructor C1_0RegisterSelf
instance Datatype D1Shutdown
instance Constructor C1_0Shutdown
instance Datatype D1ExitReason
instance Constructor C1_0ExitReason
instance Constructor C1_1ExitReason
instance Constructor C1_2ExitReason
instance Datatype D1Recipient
instance Constructor C1_0Recipient
instance Constructor C1_1Recipient
instance Constructor C1_2Recipient
instance Datatype D1ServerDisconnected
instance Constructor C1_0ServerDisconnected
instance [overlap ok] NFData ServerDisconnected
instance [overlap ok] Binary ServerDisconnected
instance [overlap ok] Binary Recipient
instance [overlap ok] NFData ExitReason
instance [overlap ok] Binary ExitReason
instance [overlap ok] NFData Shutdown
instance [overlap ok] Binary Shutdown
instance [overlap ok] NFData RegisterSelf
instance [overlap ok] Binary RegisterSelf
instance [overlap ok] NFData CancelWait
instance [overlap ok] Binary CancelWait
instance [overlap ok] (NFData a, Serializable a) => NFSerializable a
-- | Maintainers : Jeff Epstein, Tim Watson Stability : experimental
-- Portability : non-portable (requires concurrency)
--
-- This module provides a set of additional primitives that add
-- functionality to the basic Cloud Haskell APIs.
module Control.Distributed.Process.Extras.Internal.Primitives
class (Resolvable a, Routable a) => Addressable a
-- | Provides a unified API for addressing processes.
class Routable a where unresolvableMessage = baseAddressableErrorMessage
sendTo :: (Routable a, Serializable m) => a -> m -> Process ()
unsafeSendTo :: (Routable a, NFSerializable m) => a -> m -> Process ()
unresolvableMessage :: Routable a => a -> String
-- | Class of things that can be resolved to a ProcessId.
class Resolvable a
resolve :: Resolvable a => a -> Process (Maybe ProcessId)
-- | Class of things to which a Process can link itself.
class Linkable a
linkTo :: Linkable a => a -> Process ()
-- | Class of things that can be killed (or instructed to exit).
class Killable a
killProc :: Killable a => a -> String -> Process ()
exitProc :: (Killable a, Serializable m) => a -> m -> Process ()
-- | 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.
spawnSignalled :: Process a -> (a -> 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)
spawnLinkLocal :: Process () -> Process ProcessId
-- | Like spawnLinkLocal, but monitors the spawned process.
spawnMonitorLocal :: Process () -> Process (ProcessId, MonitorRef)
-- | 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.
linkOnFailure :: ProcessId -> Process ()
-- | A synchronous version of whereis, this relies on call to
-- perform the relevant monitoring of the remote node.
whereisRemote :: NodeId -> String -> Process (Maybe 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.
whereisOrStart :: String -> Process () -> Process 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.
whereisOrStartRemote :: NodeId -> String -> Closure (Process ()) -> Process (Maybe ProcessId)
-- | An alternative to matchIf that allows both predicate and action
-- to be expressed in one parameter.
matchCond :: Serializable a => (a -> Maybe (Process b)) -> Match b
-- | Safe (i.e., monitored) waiting on an expected response/message.
awaitResponse :: Addressable a => a -> [Match (Either ExitReason b)] -> Process (Either ExitReason b)
-- | Apply the supplied expression n times
times :: Int -> Process () -> Process ()
-- | Monitor any Resolvable object.
monitor :: Resolvable a => a -> Process (Maybe MonitorRef)
awaitExit :: Resolvable a => a -> Process ()
isProcessAlive :: ProcessId -> Process Bool
-- | Like forever but sans space leak
forever' :: Monad m => m a -> m b
deliver :: (Addressable a, Serializable m) => m -> a -> Process ()
__remoteTable :: RemoteTable -> RemoteTable
-- | This module provides facilities for working with time delays and
-- timeouts. The type Timeout and the timeout family of
-- functions provide mechanisms for working with
-- threadDelay-like behaviour that operates on microsecond
-- values.
--
-- The TimeInterval and TimeUnit related functions provide
-- an abstraction for working with various time intervals, whilst the
-- Delay type provides a corrolary to timeout that works
-- with these.
module Control.Distributed.Process.Extras.Time
-- | given a number, produces a TimeInterval of microseconds
microSeconds :: Int -> TimeInterval
-- | given a number, produces a TimeInterval of milliseconds
milliSeconds :: Int -> TimeInterval
-- | given a number, produces a TimeInterval of seconds
seconds :: Int -> TimeInterval
-- | given a number, produces a TimeInterval of minutes
minutes :: Int -> TimeInterval
-- | given a number, produces a TimeInterval of hours
hours :: Int -> TimeInterval
-- | converts the supplied TimeInterval to microseconds
asTimeout :: TimeInterval -> Int
-- | Convenience for making timeouts; e.g.,
--
--
-- receiveTimeout (after 3 Seconds) [ match (\"ok" -> return ()) ]
--
after :: Int -> TimeUnit -> Int
-- | Convenience for making TimeInterval; e.g.,
--
--
-- let ti = within 5 Seconds in .....
--
within :: Int -> TimeUnit -> TimeInterval
-- | converts the supplied TimeUnit to microseconds
timeToMicros :: TimeUnit -> Int -> Int
-- | A time interval.
data TimeInterval
-- | Defines the time unit for a Timeout value
data TimeUnit
Days :: TimeUnit
Hours :: TimeUnit
Minutes :: TimeUnit
Seconds :: TimeUnit
Millis :: TimeUnit
Micros :: TimeUnit
-- | Represents either a delay of TimeInterval, an infinite wait or
-- no delay (i.e., non-blocking).
data Delay
Delay :: TimeInterval -> Delay
Infinity :: Delay
NoDelay :: Delay
-- | given a TimeInterval, provide an equivalent
-- NominalDiffTim
timeIntervalToDiffTime :: TimeInterval -> NominalDiffTime
-- | given a NominalDiffTim, provide an equivalent
-- TimeInterval@
diffTimeToTimeInterval :: NominalDiffTime -> TimeInterval
-- | given a NominalDiffTim, provide an equivalent Delay@
diffTimeToDelay :: NominalDiffTime -> Delay
-- | given a Delay, provide an equivalent NominalDiffTim
delayToDiffTime :: Delay -> NominalDiffTime
-- | Create a NominalDiffTime from a number of microseconds.
microsecondsToNominalDiffTime :: Integer -> NominalDiffTime
-- | Represents a timeout in terms of microseconds, where
-- Nothing stands for infinity and Just 0, no-delay.
type Timeout = Maybe Int
-- | Send to a process when a timeout expires.
data TimeoutNotification
TimeoutNotification :: Tag -> TimeoutNotification
-- | Sends the calling process TimeoutNotification tag after
-- time microseconds
timeout :: Int -> Tag -> ProcessId -> Process ()
-- | Constructs an inifinite Timeout.
infiniteWait :: Timeout
-- | Constructs a no-wait Timeout
noWait :: Timeout
instance Typeable TimeUnit
instance Typeable TimeInterval
instance Typeable Delay
instance Typeable TimeoutNotification
instance Generic TimeUnit
instance Eq TimeUnit
instance Show TimeUnit
instance Generic TimeInterval
instance Eq TimeInterval
instance Show TimeInterval
instance Generic Delay
instance Eq Delay
instance Show Delay
instance Datatype D1TimeUnit
instance Constructor C1_0TimeUnit
instance Constructor C1_1TimeUnit
instance Constructor C1_2TimeUnit
instance Constructor C1_3TimeUnit
instance Constructor C1_4TimeUnit
instance Constructor C1_5TimeUnit
instance Datatype D1TimeInterval
instance Constructor C1_0TimeInterval
instance Datatype D1Delay
instance Constructor C1_0Delay
instance Constructor C1_1Delay
instance Constructor C1_2Delay
instance Num Delay
instance Num TimeInterval
instance Binary TimeoutNotification
instance NFData Delay
instance Binary Delay
instance NFData TimeInterval
instance Binary TimeInterval
instance NFData TimeUnit
instance Binary TimeUnit
-- |
-- - Unsafe Messaging Primitives Using NFData
--
--
-- This module mirrors
-- Control.Distributed.Process.UnsafePrimitives, but attempts to
-- provide a bit more safety by forcing evaluation before sending. This
-- is handled using NFData, by means of the
-- NFSerializable type class.
--
-- Note that we still cannot guarantee that both the
-- NFData and Binary instances will evaluate your data
-- the same way, therefore these primitives still have certain risks and
-- potential side effects. Use with caution.
module Control.Distributed.Process.Extras.UnsafePrimitives
send :: NFSerializable m => ProcessId -> m -> Process ()
nsend :: NFSerializable a => String -> a -> Process ()
sendToAddr :: (Addressable a, NFSerializable m) => a -> m -> Process ()
sendChan :: NFSerializable m => SendPort m -> m -> Process ()
-- | Create an unencoded Message for any Serializable
-- type.
wrapMessage :: NFSerializable a => a -> Message
-- | Provides an API for running code or sending messages, either after
-- some initial delay or periodically, and for cancelling, re-setting
-- and/or flushing pending timers.
module Control.Distributed.Process.Extras.Timer
-- | an opaque reference to a timer
type TimerRef = ProcessId
-- | represents a tick event that timers can generate
data Tick
Tick :: Tick
-- | blocks the calling Process for the specified TimeInterval. Note that
-- this function assumes that a blocking receive is the most efficient
-- approach to acheiving this, however the runtime semantics
-- (particularly with regards scheduling) should not differ from
-- threadDelay in practise.
sleep :: TimeInterval -> Process ()
-- | Literate way of saying sleepFor 3 Seconds.
sleepFor :: Int -> TimeUnit -> Process ()
-- | starts a timer which sends the supplied message to the destination
-- process after the specified time interval.
sendAfter :: NFSerializable a => TimeInterval -> ProcessId -> a -> Process TimerRef
-- | runs the supplied process action(s) after t has elapsed
runAfter :: TimeInterval -> Process () -> Process TimerRef
-- | calls exit pid reason after t has elapsed
exitAfter :: Serializable a => TimeInterval -> ProcessId -> a -> Process TimerRef
-- | kills the specified process after t has elapsed
killAfter :: TimeInterval -> ProcessId -> String -> Process TimerRef
-- | starts a timer that repeatedly sends the supplied message to the
-- destination process each time the specified time interval elapses. To
-- stop messages from being sent in future, cancelTimer can be
-- called.
startTimer :: NFSerializable a => TimeInterval -> ProcessId -> a -> Process TimerRef
-- | sets up a timer that sends Tick repeatedly at intervals of
-- t
ticker :: TimeInterval -> ProcessId -> Process TimerRef
-- | runs the supplied process action(s) repeatedly at intervals of
-- t
periodically :: TimeInterval -> Process () -> Process TimerRef
-- | resets a running timer. Note: Cancelling a timer does not guarantee
-- that all its messages are prevented from being delivered to the target
-- process. Also note that resetting an ongoing timer (started using the
-- startTimer or periodically functions) will only cause
-- the current elapsed period to time out, after which the timer will
-- continue running. To stop a long-running timer permanently, you should
-- use cancelTimer instead.
resetTimer :: TimerRef -> Process ()
-- | permanently cancels a timer
cancelTimer :: TimerRef -> Process ()
-- | cancels a running timer and flushes any viable timer messages from the
-- process' message queue. This function should only be called by the
-- process expecting to receive the timer's messages!
flushTimer :: (Serializable a, Eq a) => TimerRef -> a -> Delay -> Process ()
instance Typeable TimerConfig
instance Typeable Tick
instance Typeable SleepingPill
instance Generic TimerConfig
instance Eq TimerConfig
instance Show TimerConfig
instance Generic Tick
instance Eq Tick
instance Show Tick
instance Generic SleepingPill
instance Eq SleepingPill
instance Show SleepingPill
instance Datatype D1TimerConfig
instance Constructor C1_0TimerConfig
instance Constructor C1_1TimerConfig
instance Datatype D1Tick
instance Constructor C1_0Tick
instance Datatype D1SleepingPill
instance Constructor C1_0SleepingPill
instance NFData SleepingPill
instance Binary SleepingPill
instance NFData Tick
instance Binary Tick
instance NFData TimerConfig
instance Binary TimerConfig
-- |
-- - 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.
--
--
-- - 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.
module Control.Distributed.Process.Extras
class (Resolvable a, Routable a) => Addressable a
sendToRecipient :: Serializable m => Recipient -> m -> Process ()
-- | Class of things that can be resolved to a ProcessId.
class Resolvable a
resolve :: Resolvable a => a -> Process (Maybe ProcessId)
-- | Provides a unified API for addressing processes.
class Routable a where unresolvableMessage = baseAddressableErrorMessage
sendTo :: (Routable a, Serializable m) => a -> m -> Process ()
unsafeSendTo :: (Routable a, NFSerializable m) => a -> m -> Process ()
unresolvableMessage :: Routable a => a -> String
-- | Class of things to which a Process can link itself.
class Linkable a
linkTo :: Linkable a => a -> Process ()
-- | Class of things that can be killed (or instructed to exit).
class Killable a
killProc :: Killable a => a -> String -> Process ()
exitProc :: (Killable a, Serializable m) => a -> m -> Process ()
-- | 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.
class (NFData a, Serializable a) => NFSerializable a
-- | A simple means of mapping to a receiver.
data Recipient
Pid :: !ProcessId -> Recipient
Registered :: !String -> Recipient
RemoteRegistered :: !String -> !NodeId -> Recipient
-- | A ubiquitous shutdown signal that can be used to maintain a
-- consistent shutdown/stop protocol for any process that wishes to
-- handle it.
data Shutdown
Shutdown :: Shutdown
-- | Provides a reason for process termination.
data ExitReason
-- | indicates normal exit
ExitNormal :: ExitReason
-- | normal response to a Shutdown
ExitShutdown :: ExitReason
-- | abnormal (error) shutdown
ExitOther :: !String -> ExitReason
-- | Wait cancellation message.
data CancelWait
CancelWait :: CancelWait
-- | Given when a server is unobtainable.
data ServerDisconnected
ServerDisconnected :: !DiedReason -> ServerDisconnected
-- | Simple representation of a channel.
type Channel a = (SendPort a, ReceivePort a)
-- | Tags provide uniqueness for messages, so that they can be matched with
-- their response.
type Tag = Int
-- | 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.
type TagPool = MVar Tag
-- | Monitor any Resolvable object.
monitor :: Resolvable a => a -> Process (Maybe MonitorRef)
-- | 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.
spawnSignalled :: Process a -> (a -> 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)
spawnLinkLocal :: Process () -> Process ProcessId
-- | Like spawnLinkLocal, but monitors the spawned process.
spawnMonitorLocal :: Process () -> Process (ProcessId, MonitorRef)
-- | 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.
linkOnFailure :: ProcessId -> Process ()
-- | Apply the supplied expression n times
times :: Int -> Process () -> Process ()
isProcessAlive :: ProcessId -> Process Bool
-- | An alternative to matchIf that allows both predicate and action
-- to be expressed in one parameter.
matchCond :: Serializable a => (a -> Maybe (Process b)) -> Match b
deliver :: (Addressable a, Serializable m) => m -> a -> Process ()
awaitExit :: Resolvable a => a -> Process ()
-- | Safe (i.e., monitored) waiting on an expected response/message.
awaitResponse :: Addressable a => a -> [Match (Either ExitReason b)] -> Process (Either ExitReason b)
-- | Create a new per-process source of unique message identifiers.
newTagPool :: Process TagPool
-- | Extract a new identifier from a TagPool.
getTag :: TagPool -> Process Tag
-- | 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.
whereisOrStart :: String -> Process () -> Process 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.
whereisOrStartRemote :: NodeId -> String -> Closure (Process ()) -> Process (Maybe ProcessId)
__remoteTable :: RemoteTable -> RemoteTable
-- | Maintainers : Jeff Epstein, Tim Watson Stability : experimental
-- Portability : non-portable (requires concurrency)
--
-- This module provides a facility for Remote Procedure Call (rpc) style
-- interactions with Cloud Haskell processes.
--
-- Clients make synchronous calls to a running process (i.e., server)
-- using the callAt, callTimeout and multicall
-- functions. Processes acting as the server are constructed using Cloud
-- Haskell's receive family of primitives and the
-- callResponse family of functions in this module.
module Control.Distributed.Process.Extras.Call
-- | Like callTimeout, but with no timeout. Returns Nothing if the
-- target process dies.
callAt :: (Serializable a, Serializable b) => ProcessId -> a -> Tag -> Process (Maybe b)
-- | Sends a message of type a to the given process, to be handled by a
-- corresponding callResponse... function, which will send back a message
-- of type b. The tag is per-process unique identifier of the
-- transaction. If the timeout expires or the target process dies,
-- Nothing will be returned.
callTimeout :: (Serializable a, Serializable b) => ProcessId -> a -> Tag -> Timeout -> Process (Maybe b)
-- | Like callTimeout, but sends the message to multiple recipients
-- and collects the results.
multicall :: (Serializable a, Serializable b) => [ProcessId] -> a -> Tag -> Timeout -> Process [Maybe b]
-- | Produces a Match that can be used with the receiveWait family
-- of message-receiving functions. callResponse will respond to
-- a message of type a sent by callTimeout, and will respond with
-- a value of type b.
callResponse :: (Serializable a, Serializable b) => (a -> Process (b, c)) -> Match c
callResponseIf :: (Serializable a, Serializable b) => (a -> Bool) -> (a -> Process (b, c)) -> Match c
callResponseDefer :: (Serializable a, Serializable b) => (a -> (b -> Process ()) -> Process c) -> Match c
callResponseDeferIf :: (Serializable a, Serializable b) => (a -> Bool) -> (a -> (b -> Process ()) -> Process c) -> Match c
-- | Produces a Match that can be used with the receiveWait family
-- of message-receiving functions. When calllForward receives a message
-- of type from from callTimeout (and similar), it will forward
-- the message to another process, who will be responsible for responding
-- to it. It is the user's responsibility to ensure that the forwarding
-- process is linked to the destination process, so that if it fails, the
-- sender will be notified.
callForward :: Serializable a => (a -> (ProcessId, c)) -> Match c
-- | The message handling code is started in a separate thread. It's not
-- automatically linked to the calling thread, so if you want it to be
-- terminated when the message handling thread dies, you'll need to call
-- link yourself.
callResponseAsync :: (Serializable a, Serializable b) => (a -> Maybe c) -> (a -> Process b) -> Match c
instance Typeable Multicall
instance Typeable MulticallResponse
instance Eq a => Eq (MulticallResponseType a)
instance Binary MulticallResponse
instance Binary Multicall