distributed-process-client-server-0.1.3.1: The Cloud Haskell Application Platform

Copyright(c) Tim Watson 2012 - 2013
LicenseBSD3 (see the file LICENSE)
MaintainerTim Watson <watson.timothy@gmail.com>
Stabilityexperimental
Portabilitynon-portable (requires concurrency)
Safe HaskellNone
LanguageHaskell98

Control.Distributed.Process.ManagedProcess.Client

Contents

Description

The Client Portion of the Managed Process API.

Synopsis

API for client interactions with the process

sendControlMessage :: Serializable m => ControlPort m -> m -> Process () Source

Send a control message over a ControlPort.

shutdown :: ProcessId -> Process () Source

Send a signal instructing the process to terminate. The receive loop which manages the process mailbox will prioritise Shutdown signals higher than any other incoming messages, but the server might be busy (i.e., still in the process of excuting a handler) at the time of sending however, so the caller should not make any assumptions about the timeliness with which the shutdown signal will be handled. If responsiveness is important, a better approach might be to send an exit signal with Shutdown as the reason. An exit signal will interrupt any operation currently underway and force the running process to clean up and terminate.

call :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process b Source

Make a synchronous call - will block until a reply is received. The calling process will exit with ExitReason if the calls fails.

safeCall :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process (Either ExitReason b) Source

Safe version of call that returns information about the error if the operation fails. If an error occurs then the explanation will be will be stashed away as (ExitOther String).

tryCall :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process (Maybe b) Source

Version of safeCall that returns Nothing if the operation fails. If you need information about *why* a call has failed then you should use safeCall or combine catchExit and call instead.

callTimeout :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> TimeInterval -> Process (Maybe b) Source

Make a synchronous call, but timeout and return Nothing if a reply is not received within the specified time interval.

If the result of the call is a failure (or the call was cancelled) then the calling process will exit, with the ExitReason given as the reason. If the call times out however, the semantics on the server side are undefined, i.e., the server may or may not successfully process the request and may (or may not) send a response at a later time. From the callers perspective, this is somewhat troublesome, since the call result cannot be decoded directly. In this case, the flushPendingCalls API may be used to attempt to receive the message later on, however this makes no attempt whatsoever to guarantee which call response will in fact be returned to the caller. In those semantics are unsuited to your application, you might choose to exit or die in case of a timeout, or alternatively, use the callAsync API and associated waitTimeout function (in the Async API), which takes a re-usable handle on which to wait (with timeouts) multiple times.

callAsync :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process (Async b) Source

Invokes call out of band, and returns an async handle.

cast :: forall a m. (Addressable a, Serializable m) => a -> m -> Process () Source

Sends a cast message to the server identified by server. The server will not send a response. Like Cloud Haskell's send primitive, cast is fully asynchronous and never fails - therefore casting to a non-existent (e.g., dead) server process will not generate an error.

callChan :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process (ReceivePort b) Source

Sends a channel message to the server and returns a ReceivePort on which the reponse can be delivered, if the server so chooses (i.e., the might ignore the request or crash).

syncCallChan :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process b Source

A synchronous version of callChan.

syncSafeCallChan :: forall s a b. (Addressable s, Serializable a, Serializable b) => s -> a -> Process (Either ExitReason b) Source

A safe version of syncCallChan, which returns Left ExitReason if the call fails.