Control.Eff.Concurrent.Protocol

Types and functions for type-safe(er) interaction between processes.

All messages sent between processes are eventually converted to Dynamic values which carry little type information.

A step towards a more controlled and type safe process interaction model is done with the facilities defined in this module.

The metaphor for communication is a stateles protocol that describes the messages handled by a process.

A protocol is represented by a custom data type, often a phantom type, which is then used to form specific instances of type classes data/type families, to determine the messages, the replies, the servers and clients, associated with specific task, that needs to be executed concurrently.

This module contains a mechanism to specify what kind of messages (aka requests) an Endpoint can handle.

The Endpoint wraps a ProcessId and carries the protocol phantom-type, to indicate the messages that a process repsonds to.

The associated data type Pdu defines the messages or requests along with the corresponding responses.

Request handling can be either blocking, if a response is required, or non-blocking.

A process can serve a specific protocol by using the functions provided by the Control.Eff.Concurrent.Protocol.EffectfulServer and Control.Eff.Concurrent.Protocol.EffectfulServer modules.

To enable a process to use such a service, the functions provided in Control.Eff.Concurrent.Protocol.Client should be used.

Documentation

class (NFData (Pdu protocol reply), Show (Pdu protocol reply), Typeable protocol, Typeable reply) => HasPdu (protocol :: Type) (reply :: Synchronicity) where

This data family defines the protocol data units (PDU) of a protocol.

A Protocol in the sense of a communication interface description between processes.

The first parameter is usually a user defined type that identifies the protocol that uses the Pdus are. It maybe a phantom type.

The second parameter specifies if a specific constructor of an (GADT-like) Pdu instance is Synchronous, i.e. returns a result and blocks the caller or if it is Asynchronous

Example:

data BookShop deriving Typeable

instance HasPdu BookShop r where
  data instance Pdu BookShop r where
    RentBook  :: BookId   -> Pdu BookShop ('Synchronous (Either RentalError RentalId))
    BringBack :: RentalId -> Pdu BookShop 'Asynchronous
    deriving Typeable

type BookId = Int
type RentalId = Int
type RentalError = String

Since: 0.25.1

Minimal complete definition

Nothing

Associated Types

data Pdu protocol reply

The protocol data unit type for the given protocol.

Methods

deserializePdu :: Dynamic -> Maybe (Pdu protocol reply)

Deserialize a Pdu from a Dynamic i.e. from a message received by a process.

Since: 0.25.1

deserializePdu :: Typeable (Pdu protocol reply) => Dynamic -> Maybe (Pdu protocol reply)

Deserialize a Pdu from a Dynamic i.e. from a message received by a process.

Since: 0.25.1

Instances

(NFData (Pdu (Sup p) r), Show (Pdu (Sup p) r), Typeable p, Typeable r) => HasPdu (Sup p) r

Defined in Control.Eff.Concurrent.Protocol.Supervisor

Associated Types

data Pdu (Sup p) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (Sup p) r)

(Typeable o, Typeable r) => HasPdu (ObserverRegistry o) r

Defined in Control.Eff.Concurrent.Protocol.Observer

Associated Types

data Pdu (ObserverRegistry o) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (ObserverRegistry o) r)

(NFData o, Show o, Typeable o, Typeable r) => HasPdu (Observer o) r

A minimal Protocol for handling observations. This is one simple way of receiving observations - of course users can use any other Asynchronous Pdu message type for receiving observations.

Since: 0.16.0

Defined in Control.Eff.Concurrent.Protocol.Observer

Associated Types

data Pdu (Observer o) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (Observer o) r)

(HasPdu a1 r, HasPdu a2 r) => HasPdu (a1, a2) r

Defined in Control.Eff.Concurrent.Protocol

Associated Types

data Pdu (a1, a2) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (a1, a2) r)

(HasPdu a1 r, HasPdu a2 r, HasPdu a3 r) => HasPdu (a1, a2, a3) r

Defined in Control.Eff.Concurrent.Protocol

Associated Types

data Pdu (a1, a2, a3) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (a1, a2, a3) r)

(HasPdu a1 r, HasPdu a2 r, HasPdu a3 r, HasPdu a4 r) => HasPdu (a1, a2, a3, a4) r

Defined in Control.Eff.Concurrent.Protocol

Associated Types

data Pdu (a1, a2, a3, a4) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (a1, a2, a3, a4) r)

(HasPdu a1 r, HasPdu a2 r, HasPdu a3 r, HasPdu a4 r, HasPdu a5 r) => HasPdu (a1, a2, a3, a4, a5) r

Defined in Control.Eff.Concurrent.Protocol

Associated Types

data Pdu (a1, a2, a3, a4, a5) r :: Type

Methods

deserializePdu :: Dynamic -> Maybe (Pdu (a1, a2, a3, a4, a5) r)

data Synchronicity

The (promoted) constructors of this type specify (at the type level) the reply behavior of a specific constructor of an Pdu instance.

Constructors

Synchronous Type

Specify that handling a request is a blocking operation with a specific return type, e.g. ('Synchronous (Either RentalError RentalId))

Asynchronous

Non-blocking, asynchronous, request handling

type family ProtocolReply (s :: Synchronicity) where ...

This type function takes an Pdu and analysis the reply type, i.e. the Synchronicity and evaluates to either t for an Pdu x (Synchronous t) or to '()' for an Pdu x Asynchronous.

Since: 0.24.0

Equations

ProtocolReply (Synchronous t) = t

ProtocolReply Asynchronous = ()

type Tangible i = (NFData i, Typeable i, Show i)

A set of constraints for types that can evaluated via NFData, compared via Ord and presented dynamically via Typeable, and represented both as values via Show.

Since: 0.23.0

type TangiblePdu p r = (Typeable p, Typeable r, Tangible (Pdu p r))

A Constraint that bundles the requirements for the Pdu values of a protocol.

This ensures that Pdus can be strictly and deeply evaluated and shown such that for example logging is possible.

Since: 0.24.0

newtype Endpoint protocol

This is a tag-type that wraps around a ProcessId and holds an Pdu index type.

Constructors

Endpoint

Fields

• _fromEndpoint :: ProcessId

Instances

Eq (Endpoint protocol)

Defined in Control.Eff.Concurrent.Protocol

Methods

(==) :: Endpoint protocol -> Endpoint protocol -> Bool

(/=) :: Endpoint protocol -> Endpoint protocol -> Bool

Ord (Endpoint protocol)

Defined in Control.Eff.Concurrent.Protocol

Methods

compare :: Endpoint protocol -> Endpoint protocol -> Ordering

(<) :: Endpoint protocol -> Endpoint protocol -> Bool

(<=) :: Endpoint protocol -> Endpoint protocol -> Bool

(>) :: Endpoint protocol -> Endpoint protocol -> Bool

(>=) :: Endpoint protocol -> Endpoint protocol -> Bool

max :: Endpoint protocol -> Endpoint protocol -> Endpoint protocol

min :: Endpoint protocol -> Endpoint protocol -> Endpoint protocol

Typeable protocol => Show (Endpoint protocol)

Defined in Control.Eff.Concurrent.Protocol

Methods

showsPrec :: Int -> Endpoint protocol -> ShowS

show :: Endpoint protocol -> String

showList :: [Endpoint protocol] -> ShowS

NFData (Endpoint protocol)

Defined in Control.Eff.Concurrent.Protocol

Methods

rnf :: Endpoint protocol -> ()

type ToPretty (Endpoint a :: Type)

Defined in Control.Eff.Concurrent.Protocol

type ToPretty (Endpoint a :: Type) = ToPretty a <+> PutStr "endpoint"

fromEndpoint :: forall protocol protocol. Iso (Endpoint protocol) (Endpoint protocol) ProcessId ProcessId

proxyAsEndpoint :: proxy protocol -> ProcessId -> Endpoint protocol

Tag a ProcessId with an Pdu type index to mark it a Endpoint process handling that API

asEndpoint :: forall protocol. ProcessId -> Endpoint protocol

Tag a ProcessId with an Pdu type index to mark it a Endpoint process handling that API

class EmbedProtocol protocol embeddedProtocol (result :: Synchronicity) where

A class for Pdu instances that embed other Pdu. A Prism for the embedded Pdu is the center of this class

Laws: embeddedPdu = prism' embedPdu fromPdu

Since: 0.24.0

Minimal complete definition

Nothing

Methods

embeddedPdu :: Prism' (Pdu protocol result) (Pdu embeddedProtocol result)

A Prism for the embedded Pdus.

embedPdu :: Pdu embeddedProtocol result -> Pdu protocol result

Embed the Pdu value of an embedded protocol into the corresponding Pdu value.

fromPdu :: Pdu protocol result -> Maybe (Pdu embeddedProtocol result)

Examine a Pdu value from the outer protocol, and return it, if it embeds a Pdu of embedded protocol, otherwise return Nothing/

Instances

EmbedProtocol a a r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu a r) (Pdu a r)

embedPdu :: Pdu a r -> Pdu a r

fromPdu :: Pdu a r -> Maybe (Pdu a r)

EmbedProtocol (a1, a2) a2 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2) r) (Pdu a2 r)

embedPdu :: Pdu a2 r -> Pdu (a1, a2) r

fromPdu :: Pdu (a1, a2) r -> Maybe (Pdu a2 r)

EmbedProtocol (a1, a2) a1 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2) r) (Pdu a1 r)

embedPdu :: Pdu a1 r -> Pdu (a1, a2) r

fromPdu :: Pdu (a1, a2) r -> Maybe (Pdu a1 r)

EmbedProtocol (a1, a2, a3) a3 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3) r) (Pdu a3 r)

embedPdu :: Pdu a3 r -> Pdu (a1, a2, a3) r

fromPdu :: Pdu (a1, a2, a3) r -> Maybe (Pdu a3 r)

EmbedProtocol (a1, a2, a3) a2 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3) r) (Pdu a2 r)

embedPdu :: Pdu a2 r -> Pdu (a1, a2, a3) r

fromPdu :: Pdu (a1, a2, a3) r -> Maybe (Pdu a2 r)

EmbedProtocol (a1, a2, a3) a1 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3) r) (Pdu a1 r)

embedPdu :: Pdu a1 r -> Pdu (a1, a2, a3) r

fromPdu :: Pdu (a1, a2, a3) r -> Maybe (Pdu a1 r)

EmbedProtocol (a1, a2, a3, a4) a4 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4) r) (Pdu a4 r)

embedPdu :: Pdu a4 r -> Pdu (a1, a2, a3, a4) r

fromPdu :: Pdu (a1, a2, a3, a4) r -> Maybe (Pdu a4 r)

EmbedProtocol (a1, a2, a3, a4) a3 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4) r) (Pdu a3 r)

embedPdu :: Pdu a3 r -> Pdu (a1, a2, a3, a4) r

fromPdu :: Pdu (a1, a2, a3, a4) r -> Maybe (Pdu a3 r)

EmbedProtocol (a1, a2, a3, a4) a2 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4) r) (Pdu a2 r)

embedPdu :: Pdu a2 r -> Pdu (a1, a2, a3, a4) r

fromPdu :: Pdu (a1, a2, a3, a4) r -> Maybe (Pdu a2 r)

EmbedProtocol (a1, a2, a3, a4) a1 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4) r) (Pdu a1 r)

embedPdu :: Pdu a1 r -> Pdu (a1, a2, a3, a4) r

fromPdu :: Pdu (a1, a2, a3, a4) r -> Maybe (Pdu a1 r)

EmbedProtocol (a1, a2, a3, a4, a5) a5 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4, a5) r) (Pdu a5 r)

embedPdu :: Pdu a5 r -> Pdu (a1, a2, a3, a4, a5) r

fromPdu :: Pdu (a1, a2, a3, a4, a5) r -> Maybe (Pdu a5 r)

EmbedProtocol (a1, a2, a3, a4, a5) a4 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4, a5) r) (Pdu a4 r)

embedPdu :: Pdu a4 r -> Pdu (a1, a2, a3, a4, a5) r

fromPdu :: Pdu (a1, a2, a3, a4, a5) r -> Maybe (Pdu a4 r)

EmbedProtocol (a1, a2, a3, a4, a5) a3 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4, a5) r) (Pdu a3 r)

embedPdu :: Pdu a3 r -> Pdu (a1, a2, a3, a4, a5) r

fromPdu :: Pdu (a1, a2, a3, a4, a5) r -> Maybe (Pdu a3 r)

EmbedProtocol (a1, a2, a3, a4, a5) a2 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4, a5) r) (Pdu a2 r)

embedPdu :: Pdu a2 r -> Pdu (a1, a2, a3, a4, a5) r

fromPdu :: Pdu (a1, a2, a3, a4, a5) r -> Maybe (Pdu a2 r)

EmbedProtocol (a1, a2, a3, a4, a5) a1 r

Defined in Control.Eff.Concurrent.Protocol

Methods

embeddedPdu :: Prism' (Pdu (a1, a2, a3, a4, a5) r) (Pdu a1 r)

embedPdu :: Pdu a1 r -> Pdu (a1, a2, a3, a4, a5) r

fromPdu :: Pdu (a1, a2, a3, a4, a5) r -> Maybe (Pdu a1 r)

toEmbeddedEndpoint :: forall inner outer r. EmbedProtocol outer inner r => Endpoint outer -> Endpoint inner

Convert an Endpoint to an endpoint for an embedded protocol.

See EmbedProtocol, fromEmbeddedEndpoint.

Since: 0.25.1

fromEmbeddedEndpoint :: forall outer inner r. EmbedProtocol outer inner r => Endpoint inner -> Endpoint outer

Convert an Endpoint to an endpoint for a server, that embeds the protocol.

See EmbedProtocol, toEmbeddedEndpoint.

Since: 0.25.1

prettyTypeableShows :: SomeTypeRep -> ShowS

This is equivalent to prettyTypeableShowsPrec 0

Since: 0.24.0

prettyTypeableShowsPrec :: Int -> SomeTypeRep -> ShowS

An internal utility to print Typeable without the kinds. This is like showsPrec in that it accepts a precedence parameter, and the result is in parentheses when the precedence is higher than 9.

Since: 0.24.0