System.ZMQ4.Monadic

This modules exposes a monadic interface of ZMQ4. Actions run inside a ZMQ monad and Sockets are guaranteed not to leak outside their corresponding runZMQ scope. Running ZMQ computations asynchronously is directly supported through async.

Type Definitions

data ZMQ z a

The ZMQ monad is modeled after ST and encapsulates a Context. It uses the uninstantiated type variable z to distinguish different invoctions of runZMQ and to prevent unintented use of Sockets outside their scope. Cf. the paper of John Launchbury and Simon Peyton Jones Lazy Functional State Threads.

Instances

Monad (ZMQ z)

Functor (ZMQ z)

Applicative (ZMQ z)

MonadThrow (ZMQ z)

MonadCatch (ZMQ z)

MonadMask (ZMQ z)

MonadIO (ZMQ z)

data Socket z t

The ZMQ socket, parameterised by SocketType and belonging to a particular ZMQ thread.

Instances

SocketLike (Socket z)

data Flag

Flags to apply on send operations (cf. man zmq_send)

Constructors

DontWait

ZMQ_DONTWAIT (Only relevant on Windows.)

SendMore

ZMQ_SNDMORE

Instances

Eq Flag

Ord Flag

Show Flag

data Switch

Configuration switch

Constructors

Default

Use default setting

On

Activate setting

Off

De-activate setting

Instances

Eq Switch

Ord Switch

Show Switch

type Timeout = Int64

data Event

Socket events.

Constructors

In

ZMQ_POLLIN (incoming messages)

Out

ZMQ_POLLOUT (outgoing messages, i.e. at least 1 byte can be written)

Err

ZMQ_POLLERR

Instances

Eq Event

Ord Event

Read Event

Show Event

data EventType

Event types to monitor.

Constructors

ConnectedEvent

ConnectDelayedEvent

ConnectRetriedEvent

ListeningEvent

BindFailedEvent

AcceptedEvent

AcceptFailedEvent

ClosedEvent

CloseFailedEvent

DisconnectedEvent

MonitorStoppedEvent

AllEvents

Instances

Eq EventType

Ord EventType

Show EventType

data EventMsg

Event Message to receive when monitoring socket events.

Constructors

Connected !ByteString !Fd

ConnectDelayed !ByteString

ConnectRetried !ByteString !Int

Listening !ByteString !Fd

BindFailed !ByteString !Int

Accepted !ByteString !Fd

AcceptFailed !ByteString !Int

Closed !ByteString !Fd

CloseFailed !ByteString !Int

Disconnected !ByteString !Fd

MonitorStopped !ByteString !Int

Instances

Eq EventMsg

Show EventMsg

data Poll s m where

A Poll value contains the object to poll (a 0MQ socket or a file descriptor), the set of Events which are of interest and--optionally-- a callback-function which is invoked iff the set of interested events overlaps with the actual events.

Constructors

Sock :: s t -> [Event] -> Maybe ([Event] -> m ()) -> Poll s m

File :: Fd -> [Event] -> Maybe ([Event] -> m ()) -> Poll s m

data KeyFormat a where

Constructors

BinaryFormat :: KeyFormat Div4

TextFormat :: KeyFormat Div5

Instances

Eq (KeyFormat a)

Show (KeyFormat a)

data SecurityMechanism

Constructors

Null

Plain

Curve

Instances

Eq SecurityMechanism

Show SecurityMechanism

Socket type-classes

class SocketType a

Socket types.

Minimal complete definition

zmqSocketType

Instances

SocketType Stream

SocketType Push

SocketType Pull

SocketType Router

SocketType Dealer

SocketType Rep

SocketType Req

SocketType XSub

SocketType XPub

SocketType Sub

SocketType Pub

SocketType Pair

class Sender a

Sockets which can send.

Instances

Sender Stream

Sender Push

Sender Router

Sender Dealer

Sender Rep

Sender Req

Sender XSub

Sender XPub

Sender Pub

Sender Pair

class Receiver a

Sockets which can receive.

Instances

Receiver Stream

Receiver Pull

Receiver Router

Receiver Dealer

Receiver Rep

Receiver Req

Receiver XSub

Receiver XPub

Receiver Sub

Receiver Pair

class Subscriber a

Sockets which can subscribe.

Instances

Subscriber Sub

class SocketLike s

Minimal complete definition

toSocket

Instances

SocketLike Socket

SocketLike (Socket z)

class Conflatable a

Sockets which can be conflated.

Instances

Conflatable Push

Conflatable Pull

Conflatable Dealer

Conflatable Sub

Conflatable Pub

class SendProbe a

Sockets which can send probes (cf. setProbeRouter).

Instances

SendProbe Router

SendProbe Dealer

SendProbe Req

Socket Types

data Pair

ZMQ_PAIR

Constructors

Pair

Instances

Eq Pair

Generic Pair

SocketType Pair

Receiver Pair

Sender Pair

Typeable * Pair

type Rep Pair

data Pub

ZMQ_PUB

Constructors

Pub

Instances

Eq Pub

Generic Pub

SocketType Pub

Conflatable Pub

Sender Pub

Typeable * Pub

type Rep Pub

data Sub

ZMQ_SUB

Constructors

Sub

Instances

Eq Sub

Generic Sub

SocketType Sub

Conflatable Sub

Receiver Sub

Subscriber Sub

Typeable * Sub

type Rep Sub

data XPub

ZMQ_XPUB

Constructors

XPub

Instances

Eq XPub

Generic XPub

SocketType XPub

Receiver XPub

Sender XPub

Typeable * XPub

type Rep XPub

data XSub

ZMQ_XSUB

Constructors

XSub

Instances

Eq XSub

Generic XSub

SocketType XSub

Receiver XSub

Sender XSub

Typeable * XSub

type Rep XSub

data Req

ZMQ_REQ

Constructors

Req

Instances

Eq Req

Generic Req

SocketType Req

SendProbe Req

Receiver Req

Sender Req

Typeable * Req

type Rep Req

data Rep

ZMQ_REP

Constructors

Rep

Instances

Eq Rep

Generic Rep

SocketType Rep

Receiver Rep

Sender Rep

Typeable * Rep

type Rep Rep

data Dealer

ZMQ_DEALER

Constructors

Dealer

Instances

Eq Dealer

Generic Dealer

SocketType Dealer

SendProbe Dealer

Conflatable Dealer

Receiver Dealer

Sender Dealer

Typeable * Dealer

type Rep Dealer

data Router

ZMQ_ROUTER

Constructors

Router

Instances

Eq Router

Generic Router

SocketType Router

SendProbe Router

Receiver Router

Sender Router

Typeable * Router

type Rep Router

data Pull

ZMQ_PULL

Constructors

Pull

Instances

Eq Pull

Generic Pull

SocketType Pull

Conflatable Pull

Receiver Pull

Typeable * Pull

type Rep Pull

data Push

ZMQ_PUSH

Constructors

Push

Instances

Eq Push

Generic Push

SocketType Push

Conflatable Push

Sender Push

Typeable * Push

type Rep Push

data Stream

ZMQ_STREAM

Constructors

Stream

Instances

Eq Stream

Generic Stream

SocketType Stream

Receiver Stream

Sender Stream

Typeable * Stream

type Rep Stream

General Operations

version :: ZMQ z (Int, Int, Int)

runZMQ :: MonadIO m => (forall z. ZMQ z a) -> m a

Return the value computed by the given ZMQ monad. Rank-2 polymorphism is used to prevent leaking of z. An invocation of runZMQ will internally create a Context and all actions are executed relative to this context. On finish the context will be disposed, but see async.

async :: ZMQ z a -> ZMQ z (Async a)

Run the given ZMQ computation asynchronously, i.e. this function runs the computation in a new thread using async. N.B. reference counting is used to prolong the lifetime of the Context encapsulated in ZMQ as necessary, e.g.:

runZMQ $ do
    s <- socket Pair
    async $ do
        liftIO (threadDelay 10000000)
        identity s >>= liftIO . print

Here, runZMQ will finish before the code section in async, but due to reference counting, the Context will only be disposed after async finishes as well.

socket :: SocketType t => t -> ZMQ z (Socket z t)

ZMQ Options (Read)

ioThreads :: ZMQ z Word

maxSockets :: ZMQ z Word

ZMQ Options (Write)

setIoThreads :: Word -> ZMQ z ()

setMaxSockets :: Word -> ZMQ z ()

Socket operations

close :: Socket z t -> ZMQ z ()

bind :: Socket z t -> String -> ZMQ z ()

unbind :: Socket z t -> String -> ZMQ z ()

connect :: Socket z t -> String -> ZMQ z ()

disconnect :: Socket z t -> String -> ZMQ z ()

send :: Sender t => Socket z t -> [Flag] -> ByteString -> ZMQ z ()

send' :: Sender t => Socket z t -> [Flag] -> ByteString -> ZMQ z ()

sendMulti :: Sender t => Socket z t -> NonEmpty ByteString -> ZMQ z ()

receive :: Receiver t => Socket z t -> ZMQ z ByteString

receiveMulti :: Receiver t => Socket z t -> ZMQ z [ByteString]

subscribe :: Subscriber t => Socket z t -> ByteString -> ZMQ z ()

unsubscribe :: Subscriber t => Socket z t -> ByteString -> ZMQ z ()

proxy :: Socket z a -> Socket z b -> Maybe (Socket z c) -> ZMQ z ()

monitor :: [EventType] -> Socket z t -> ZMQ z (Bool -> IO (Maybe EventMsg))

socketMonitor :: [EventType] -> String -> Socket z t -> ZMQ z ()

poll :: (SocketLike s, MonadIO m) => Timeout -> [Poll s m] -> m [[Event]]

Polls for events on the given Poll descriptors. Returns a list of events per descriptor which have occured. (cf. zmq_poll)

Socket Options (Read)

affinity :: Socket z t -> ZMQ z Word64

backlog :: Socket z t -> ZMQ z Int

conflate :: Conflatable t => Socket z t -> ZMQ z Bool

curvePublicKey :: KeyFormat f -> Socket z t -> ZMQ z ByteString

curveSecretKey :: KeyFormat f -> Socket z t -> ZMQ z ByteString

curveServerKey :: KeyFormat f -> Socket z t -> ZMQ z ByteString

delayAttachOnConnect :: Socket z t -> ZMQ z Bool

Deprecated: Use immediate

events :: Socket z t -> ZMQ z [Event]

fileDescriptor :: Socket z t -> ZMQ z Fd

identity :: Socket z t -> ZMQ z ByteString

immediate :: Socket z t -> ZMQ z Bool

ipv4Only :: Socket z t -> ZMQ z Bool

Deprecated: Use ipv6

ipv6 :: Socket z t -> ZMQ z Bool

lastEndpoint :: Socket z t -> ZMQ z String

linger :: Socket z t -> ZMQ z Int

maxMessageSize :: Socket z t -> ZMQ z Int64

mcastHops :: Socket z t -> ZMQ z Int

mechanism :: Socket z t -> ZMQ z SecurityMechanism

moreToReceive :: Socket z t -> ZMQ z Bool

plainServer :: Socket z t -> ZMQ z Bool

plainPassword :: Socket z t -> ZMQ z ByteString

plainUserName :: Socket z t -> ZMQ z ByteString

rate :: Socket z t -> ZMQ z Int

receiveBuffer :: Socket z t -> ZMQ z Int

receiveHighWM :: Socket z t -> ZMQ z Int

receiveTimeout :: Socket z t -> ZMQ z Int

reconnectInterval :: Socket z t -> ZMQ z Int

reconnectIntervalMax :: Socket z t -> ZMQ z Int

recoveryInterval :: Socket z t -> ZMQ z Int

sendBuffer :: Socket z t -> ZMQ z Int

sendHighWM :: Socket z t -> ZMQ z Int

sendTimeout :: Socket z t -> ZMQ z Int

tcpKeepAlive :: Socket z t -> ZMQ z Switch

tcpKeepAliveCount :: Socket z t -> ZMQ z Int

tcpKeepAliveIdle :: Socket z t -> ZMQ z Int

tcpKeepAliveInterval :: Socket z t -> ZMQ z Int

zapDomain :: Socket z t -> ZMQ z ByteString

Socket Options (Write)

setAffinity :: Word64 -> Socket z t -> ZMQ z ()

setBacklog :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setConflate :: Conflatable t => Bool -> Socket z t -> ZMQ z ()

setCurveServer :: Bool -> Socket z t -> ZMQ z ()

setCurvePublicKey :: KeyFormat f -> Restricted f ByteString -> Socket z t -> ZMQ z ()

setCurveSecretKey :: KeyFormat f -> Restricted f ByteString -> Socket z t -> ZMQ z ()

setCurveServerKey :: KeyFormat f -> Restricted f ByteString -> Socket z t -> ZMQ z ()

setDelayAttachOnConnect :: Bool -> Socket z t -> ZMQ z ()

Deprecated: Use setImmediate

setIdentity :: Restricted (N1, N254) ByteString -> Socket z t -> ZMQ z ()

setImmediate :: Bool -> Socket z t -> ZMQ z ()

setIpv4Only :: Bool -> Socket z t -> ZMQ z ()

Deprecated: Use setIpv6

setIpv6 :: Bool -> Socket z t -> ZMQ z ()

setLinger :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setMaxMessageSize :: Integral i => Restricted (Nneg1, Int64) i -> Socket z t -> ZMQ z ()

setMcastHops :: Integral i => Restricted (N1, Int32) i -> Socket z t -> ZMQ z ()

setPlainServer :: Bool -> Socket z t -> ZMQ z ()

setPlainPassword :: Restricted (N1, N254) ByteString -> Socket z t -> ZMQ z ()

setPlainUserName :: Restricted (N1, N254) ByteString -> Socket z t -> ZMQ z ()

setProbeRouter :: SendProbe t => Bool -> Socket z t -> ZMQ z ()

setRate :: Integral i => Restricted (N1, Int32) i -> Socket z t -> ZMQ z ()

setReceiveBuffer :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setReceiveHighWM :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setReceiveTimeout :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setReconnectInterval :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setReconnectIntervalMax :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setRecoveryInterval :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setReqCorrelate :: Bool -> Socket z Req -> ZMQ z ()

setReqRelaxed :: Bool -> Socket z Req -> ZMQ z ()

setRouterMandatory :: Bool -> Socket z Router -> ZMQ z ()

setSendBuffer :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setSendHighWM :: Integral i => Restricted (N0, Int32) i -> Socket z t -> ZMQ z ()

setSendTimeout :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setTcpAcceptFilter :: Maybe ByteString -> Socket z t -> ZMQ z ()

setTcpKeepAlive :: Switch -> Socket z t -> ZMQ z ()

setTcpKeepAliveCount :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setTcpKeepAliveIdle :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setTcpKeepAliveInterval :: Integral i => Restricted (Nneg1, Int32) i -> Socket z t -> ZMQ z ()

setXPubVerbose :: Bool -> Socket z XPub -> ZMQ z ()

Error Handling

data ZMQError

ZMQError encapsulates information about errors, which occur when using the native 0MQ API, such as error number and message.

Instances

Eq ZMQError

Ord ZMQError

Show ZMQError

Exception ZMQError

Typeable * ZMQError

errno :: ZMQError -> Int

Error number value.

source :: ZMQError -> String

Source where this error originates from.

message :: ZMQError -> String

Actual error message.

Re-exports

liftIO :: MonadIO m => forall a. IO a -> m a

Lift a computation from the IO monad.

restrict :: Restriction r v => v -> Restricted r v

Create a restricted value. If the given value does not satisfy the restrictions, a modified variant is used instead, e.g. if an integer is larger than the upper bound, the upper bound value is used.

toRestricted :: Restriction r v => v -> Maybe (Restricted r v)

Create a restricted value. Returns Nothing if the given value does not satisfy all restrictions.

Low-level Functions

waitRead :: Socket z t -> ZMQ z ()

waitWrite :: Socket z t -> ZMQ z ()

z85Encode :: MonadIO m => Restricted Div4 ByteString -> m ByteString

z85Decode :: MonadIO m => Restricted Div5 ByteString -> m ByteString

curveKeyPair :: MonadIO m => m (Restricted Div5 ByteString, Restricted Div5 ByteString)

Generate a new curve key pair. (cf. zmq_curve_keypair)