Control.Eff.Concurrent.Protocol

This module contains a mechanism to specify what kind of messages (aka requests) a Endpoint (Process) can handle, and if the caller blocks and waits for an answer, which the server process provides.

The type magic in the Pdu type family allows to define a related set of 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 Pdu instance by using the functions provided by the Control.Eff.Concurrent.Pdu.Server module.

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

Documentation

data family Pdu (protocol :: Type) (reply :: Synchronicity)

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

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

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

Instances

(Show (Pdu a1 r), Show (Pdu a2 r)) => Show (Pdu (a1, a2) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

showsPrec :: Int -> Pdu (a1, a2) r -> ShowS

show :: Pdu (a1, a2) r -> String

showList :: [Pdu (a1, a2) r] -> ShowS

(Show (Pdu a1 r), Show (Pdu a2 r), Show (Pdu a3 r)) => Show (Pdu (a1, a2, a3) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

showsPrec :: Int -> Pdu (a1, a2, a3) r -> ShowS

show :: Pdu (a1, a2, a3) r -> String

showList :: [Pdu (a1, a2, a3) r] -> ShowS

(Show (Pdu a1 r), Show (Pdu a2 r), Show (Pdu a3 r), Show (Pdu a4 r)) => Show (Pdu (a1, a2, a3, a4) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

showsPrec :: Int -> Pdu (a1, a2, a3, a4) r -> ShowS

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

showList :: [Pdu (a1, a2, a3, a4) r] -> ShowS

(Show (Pdu a1 r), Show (Pdu a2 r), Show (Pdu a3 r), Show (Pdu a4 r), Show (Pdu a5 r)) => Show (Pdu (a1, a2, a3, a4, a5) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

showsPrec :: Int -> Pdu (a1, a2, a3, a4, a5) r -> ShowS

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

showList :: [Pdu (a1, a2, a3, a4, a5) r] -> ShowS

Show (ChildId p) => Show (Pdu (Sup p) (Synchronous r))

Defined in Control.Eff.Concurrent.Protocol.Supervisor

Methods

showsPrec :: Int -> Pdu (Sup p) (Synchronous r) -> ShowS

show :: Pdu (Sup p) (Synchronous r) -> String

showList :: [Pdu (Sup p) (Synchronous r)] -> ShowS

Show (Pdu (ObserverRegistry o) r)

Defined in Control.Eff.Concurrent.Protocol.Observer

Methods

showsPrec :: Int -> Pdu (ObserverRegistry o) r -> ShowS

show :: Pdu (ObserverRegistry o) r -> String

showList :: [Pdu (ObserverRegistry o) r] -> ShowS

Show o => Show (Pdu (Observer o) r)

Defined in Control.Eff.Concurrent.Protocol.Observer

Methods

showsPrec :: Int -> Pdu (Observer o) r -> ShowS

show :: Pdu (Observer o) r -> String

showList :: [Pdu (Observer o) r] -> ShowS

(NFData (Pdu a1 r), NFData (Pdu a2 r)) => NFData (Pdu (a1, a2) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

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

(NFData (Pdu a1 r), NFData (Pdu a2 r), NFData (Pdu a3 r)) => NFData (Pdu (a1, a2, a3) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

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

(NFData (Pdu a1 r), NFData (Pdu a2 r), NFData (Pdu a3 r), NFData (Pdu a4 r)) => NFData (Pdu (a1, a2, a3, a4) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

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

(NFData (Pdu a1 r), NFData (Pdu a2 r), NFData (Pdu a3 r), NFData (Pdu a4 r), NFData (Pdu a5 r)) => NFData (Pdu (a1, a2, a3, a4, a5) r)

Defined in Control.Eff.Concurrent.Protocol

Methods

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

NFData (ChildId p) => NFData (Pdu (Sup p) (Synchronous r))

Defined in Control.Eff.Concurrent.Protocol.Supervisor

Methods

rnf :: Pdu (Sup p) (Synchronous r) -> ()

NFData (Pdu (ObserverRegistry o) r)

Defined in Control.Eff.Concurrent.Protocol.Observer

Methods

rnf :: Pdu (ObserverRegistry o) r -> ()

NFData o => NFData (Pdu (Observer o) Asynchronous)

Defined in Control.Eff.Concurrent.Protocol.Observer

Methods

rnf :: Pdu (Observer o) Asynchronous -> ()

data Pdu (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

data Pdu (Observer o) r where

• Observed :: forall o (r :: Synchronicity). o -> Pdu (Observer o) Asynchronous

type ToPretty (Pdu x y :: Type)

Defined in Control.Eff.Concurrent.Protocol

type ToPretty (Pdu x y :: Type) = PrettySurrounded (PutStr "<") (PutStr ">") (("protocol" <:> ToPretty x) <+> ToPretty y)

data Pdu (a1, a2) x

Defined in Control.Eff.Concurrent.Protocol

data Pdu (a1, a2) x

• = ToPduLeft (Pdu a1 r)
• | ToPduRight (Pdu a2 r)

data Pdu (Sup p) r

The Pdu instance contains methods to start, stop and lookup a child process, as well as a diagnostic callback.

Since: 0.23.0

Defined in Control.Eff.Concurrent.Protocol.Supervisor

data Pdu (Sup p) r where

• StartC :: forall k (p :: k) (r :: Synchronicity) p. ChildId p -> Pdu (Sup p) (Synchronous (Either (SpawnErr p) (Endpoint (Protocol p))))
• StopC :: forall k (p :: k) (r :: Synchronicity) p. ChildId p -> Timeout -> Pdu (Sup p) (Synchronous Bool)
• LookupC :: forall k (p :: k) (r :: Synchronicity) p. ChildId p -> Pdu (Sup p) (Synchronous (Maybe (Endpoint (Protocol p))))
• GetDiagnosticInfo :: forall k (p :: k) (r :: Synchronicity). Pdu (Sup p) (Synchronous Text)

data Pdu (ObserverRegistry o) r

Protocol for managing observers. This can be added to any server for any number of different observation types. The functions manageObservers and handleObserverRegistration are used to include observer handling;

Since: 0.16.0

Defined in Control.Eff.Concurrent.Protocol.Observer

data Pdu (ObserverRegistry o) r where

• RegisterObserver :: forall k (o :: k) (r :: Synchronicity) o. NFData o => Observer o -> Pdu (ObserverRegistry o) Asynchronous
• ForgetObserver :: forall k (o :: k) (r :: Synchronicity) o. NFData o => Observer o -> Pdu (ObserverRegistry o) Asynchronous

data Pdu (a1, a2, a3) x

Defined in Control.Eff.Concurrent.Protocol

data Pdu (a1, a2, a3) x

• = ToPdu1 (Pdu a1 r)
• | ToPdu2 (Pdu a2 r)
• | ToPdu3 (Pdu a3 r)

data Pdu (a1, a2, a3, a4) x

Defined in Control.Eff.Concurrent.Protocol

data Pdu (a1, a2, a3, a4) x

• = ToPdu1Of4 (Pdu a1 r)
• | ToPdu2Of4 (Pdu a2 r)
• | ToPdu3Of4 (Pdu a3 r)
• | ToPdu4Of4 (Pdu a4 r)

data Pdu (a1, a2, a3, a4, a5) x

Defined in Control.Eff.Concurrent.Protocol

data Pdu (a1, a2, a3, a4, a5) x

• = ToPdu1Of5 (Pdu a1 r)
• | ToPdu2Of5 (Pdu a2 r)
• | ToPdu3Of5 (Pdu a3 r)
• | ToPdu4Of5 (Pdu a4 r)
• | ToPdu5Of5 (Pdu 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 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 r -> Pdu protocol r

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

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

embedPdu :: Pdu a r -> Pdu a r

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

EmbedProtocol (a1, a2) a2

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

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

EmbedProtocol (a1, a2) a1

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

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

EmbedProtocol (a1, a2, a3) a3

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

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

EmbedProtocol (a1, a2, a3) a2

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

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

EmbedProtocol (a1, a2, a3) a1

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

Defined in Control.Eff.Concurrent.Protocol

Methods

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

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

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

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