Portability	non-portable
Stability	experimental
Maintainer	Toralf Wittner <tw@dtex.org>
Safe Haskell	None

System.ZMQ4

Contents

Type Definitions
General Operations
Context Options (Read)
Context Options (Write)
Socket Options (Read)
Socket Options (Write)
Restrictions
Error Handling
Low-level Functions
Utils

Description

0MQ haskell binding. The API closely follows the C-API of 0MQ with the main difference being that sockets are typed.

Notes

Many option settings use a Restriction to further constrain the range of possible values of their integral types. For example the maximum message size can be given as -1, which means no limit or by greater values, which denote the message size in bytes. The type of setMaxMessageSize is therefore:

setMaxMessageSize :: Integral i
                    => Restricted (Nneg1, Int64) i
                    -> Socket a
                    -> IO ()

which means any integral value in the range of -1 to (maxBound :: Int64) can be given. To create a restricted value from plain value, use toRestricted or restrict.

Synopsis

Type Definitions

Socket Types

data Pair Source

ZMQ_PAIR

Constructors

Pair

Instances

Eq Pair
Typeable Pair
Generic Pair
SocketType Pair
Receiver Pair
Sender Pair

data Pub Source

ZMQ_PUB

Constructors

Pub

Instances

Eq Pub
Typeable Pub
Generic Pub
SocketType Pub
Conflatable Pub
Sender Pub

data Sub Source

ZMQ_SUB

Constructors

Sub

Instances

Eq Sub
Typeable Sub
Generic Sub
SocketType Sub
Conflatable Sub
Receiver Sub
Subscriber Sub

data XPub Source

ZMQ_XPUB

Constructors

XPub

Instances

Eq XPub
Typeable XPub
Generic XPub
SocketType XPub
Receiver XPub
Sender XPub

data XSub Source

ZMQ_XSUB

Constructors

XSub

Instances

Eq XSub
Typeable XSub
Generic XSub
SocketType XSub
Receiver XSub
Sender XSub

data Req Source

ZMQ_REQ

Constructors

Req

Instances

Eq Req
Typeable Req
Generic Req
SocketType Req
SendProbe Req
Receiver Req
Sender Req

data Rep Source

ZMQ_REP

Constructors

Rep

Instances

Eq Rep
Typeable Rep
Generic Rep
SocketType Rep
Receiver Rep
Sender Rep

data Dealer Source

ZMQ_DEALER

Constructors

Dealer

Instances

Eq Dealer
Typeable Dealer
Generic Dealer
SocketType Dealer
SendProbe Dealer
Conflatable Dealer
Receiver Dealer
Sender Dealer

data Router Source

ZMQ_ROUTER

Constructors

Router

Instances

Eq Router
Typeable Router
Generic Router
SocketType Router
SendProbe Router
Receiver Router
Sender Router

type XReq = Dealer Source

Deprecated: Use Dealer

type XRep = Router Source

Deprecated: Use Router

data Pull Source

ZMQ_PULL

Constructors

Pull

Instances

Eq Pull
Typeable Pull
Generic Pull
SocketType Pull
Conflatable Pull
Receiver Pull

data Push Source

ZMQ_PUSH

Constructors

Push

Instances

Eq Push
Typeable Push
Generic Push
SocketType Push
Conflatable Push
Sender Push

data Stream Source

ZMQ_STREAM

Constructors

Stream

Instances

Eq Stream
Typeable Stream
Generic Stream
SocketType Stream
Receiver Stream
Sender Stream

Socket type-classes

class SocketType a Source

Socket types.

class Sender a Source

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 Source

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 Source

Sockets which can subscribe.

Instances

Subscriber Sub

class SocketLike s Source

Instances

SocketLike Socket
SocketLike (Socket z)

class Conflatable a Source

Sockets which can be conflated.

Instances

Conflatable Push
Conflatable Pull
Conflatable Dealer
Conflatable Sub
Conflatable Pub

class SendProbe a Source

Sockets which can send probes (cf. setProbeRouter).

Instances

SendProbe Router
SendProbe Dealer
SendProbe Req

Various type definitions

type Size = Word Source

data Context Source

A 0MQ context representation.

data Socket a Source

A 0MQ Socket.

Instances

SocketLike Socket

data Flag Source

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 Source

Configuration switch

Constructors

Default	Use default setting
On	Activate setting
Off	De-activate setting

Instances

Eq Switch
Ord Switch
Show Switch

type Timeout = Int64 Source

data Event Source

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 Source

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 Source

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 whereSource

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 whereSource

Constructors

BinaryFormat :: KeyFormat Div4
TextFormat :: KeyFormat Div5

Instances

Eq (KeyFormat a)
Show (KeyFormat a)

data SecurityMechanism Source

Constructors

Null
Plain
Curve

Instances

Eq SecurityMechanism
Show SecurityMechanism

General Operations

withContext :: (Context -> IO a) -> IO aSource

Run an action with a 0MQ context. The Context supplied to your action will not be valid after the action either returns or throws an exception.

withSocket :: SocketType a => Context -> a -> (Socket a -> IO b) -> IO bSource

Run an action with a 0MQ socket. The socket will be closed after running the supplied action even if an error occurs. The socket supplied to your action will not be valid after the action terminates.

bind :: Socket a -> String -> IO ()Source

Bind the socket to the given address (cf. zmq_bind).

unbind :: Socket a -> String -> IO ()Source

Unbind the socket from the given address (cf. zmq_unbind).

connect :: Socket a -> String -> IO ()Source

Connect the socket to the given address (cf. zmq_connect).

disconnect :: Socket a -> String -> IO ()Source

Disconnect the socket from the given endpoint (cf. zmq_disconnect).

send :: Sender a => Socket a -> [Flag] -> ByteString -> IO ()Source

Send the given ByteString over the socket (cf. zmq_sendmsg).

Note: This function always calls zmq_sendmsg in a non-blocking way, i.e. there is no need to provide the ZMQ_DONTWAIT flag as this is used by default. Still send is blocking the thread as long as the message can not be queued on the socket using GHC's threadWaitWrite.

send' :: Sender a => Socket a -> [Flag] -> ByteString -> IO ()Source

Send the given ByteString over the socket (cf. zmq_sendmsg).

This is operationally identical to send socket (Strict.concat (Lazy.toChunks lbs)) flags but may be more efficient.

Note: This function always calls zmq_sendmsg in a non-blocking way, i.e. there is no need to provide the ZMQ_DONTWAIT flag as this is used by default. Still send' is blocking the thread as long as the message can not be queued on the socket using GHC's threadWaitWrite.

sendMulti :: Sender a => Socket a -> NonEmpty ByteString -> IO ()Source

Send a multi-part message. This function applies the SendMore Flag between all message parts. 0MQ guarantees atomic delivery of a multi-part message (cf. zmq_sendmsg).

receive :: Receiver a => Socket a -> IO ByteString Source

Receive a ByteString from socket (cf. zmq_recvmsg).

Note: This function always calls zmq_recvmsg in a non-blocking way, i.e. there is no need to provide the ZMQ_DONTWAIT flag as this is used by default. Still receive is blocking the thread as long as no data is available using GHC's threadWaitRead.

receiveMulti :: Receiver a => Socket a -> IO [ByteString]Source

Receive a multi-part message. This function collects all message parts send via sendMulti.

version :: IO (Int, Int, Int)Source

Return the runtime version of the underlying 0MQ library as a (major, minor, patch) triple.

monitor :: [EventType] -> Context -> Socket a -> IO (Bool -> IO (Maybe EventMsg))Source

Monitor socket events (cf. zmq_socket_monitor).

This function returns a function which can be invoked to retrieve the next socket event, potentially blocking until the next one becomes available. When applied to False, monitoring will terminate, i.e. internal monitoring resources will be disposed. Consequently after monitor has been invoked, the returned function must be applied once to False.

socketMonitor :: [EventType] -> String -> Socket a -> IO ()Source

Setup socket monitoring, i.e. a Pair socket which sends monitoring events about the given Socket to the given address.

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

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

subscribe :: Subscriber a => Socket a -> ByteString -> IO ()Source

Subscribe Socket to given subscription.

unsubscribe :: Subscriber a => Socket a -> ByteString -> IO ()Source

Unsubscribe Socket from given subscription.

Context Options (Read)

ioThreads :: Context -> IO Word Source

zmq_ctx_get ZMQ_IO_THREADS.

maxSockets :: Context -> IO Word Source

zmq_ctx_get ZMQ_MAX_SOCKETS.

Context Options (Write)

setIoThreads :: Word -> Context -> IO ()Source

zmq_ctx_get ZMQ_IO_THREADS.

setMaxSockets :: Word -> Context -> IO ()Source

zmq_ctx_get ZMQ_MAX_SOCKETS.

Socket Options (Read)

affinity :: Socket a -> IO Word64 Source

zmq_getsockopt ZMQ_AFFINITY.

backlog :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_BACKLOG.

conflate :: Conflatable a => Socket a -> IO Bool Source

Restricts the outgoing and incoming socket buffers to a single message.

curvePublicKey :: KeyFormat f -> Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_CURVE_PUBLICKEY.

curveSecretKey :: KeyFormat f -> Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_CURVE_SECRETKEY.

curveServerKey :: KeyFormat f -> Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_CURVE_SERVERKEY.

delayAttachOnConnect :: Socket a -> IO Bool Source

Deprecated: Use immediate

events :: Socket a -> IO [Event]Source

zmq_getsockopt ZMQ_EVENTS.

fileDescriptor :: Socket a -> IO Fd Source

zmq_getsockopt ZMQ_FD.

identity :: Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_IDENTITY.

immediate :: Socket a -> IO Bool Source

zmq_getsockopt ZMQ_IMMEDIATE.

ipv4Only :: Socket a -> IO Bool Source

Deprecated: Use ipv6

ipv6 :: Socket a -> IO Bool Source

zmq_getsockopt ZMQ_IPV6.

lastEndpoint :: Socket a -> IO String Source

zmq_getsockopt ZMQ_LAST_ENDPOINT.

linger :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_LINGER.

maxMessageSize :: Socket a -> IO Int64 Source

zmq_getsockopt ZMQ_MAXMSGSIZE.

mcastHops :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_MULTICAST_HOPS.

mechanism :: Socket a -> IO SecurityMechanism Source

zmq_getsockopt ZMQ_MECHANISM.

moreToReceive :: Socket a -> IO Bool Source

zmq_getsockopt ZMQ_RCVMORE.

plainServer :: Socket a -> IO Bool Source

zmq_getsockopt ZMQ_PLAIN_SERVER.

plainPassword :: Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_PLAIN_PASSWORD.

plainUserName :: Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_PLAIN_USERNAME.

rate :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RATE.

receiveBuffer :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RCVBUF.

receiveHighWM :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RCVHWM.

receiveTimeout :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RCVTIMEO.

reconnectInterval :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RECONNECT_IVL.

reconnectIntervalMax :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RECONNECT_IVL_MAX.

recoveryInterval :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_RECOVERY_IVL.

sendBuffer :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_SNDBUF.

sendHighWM :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_SNDHWM.

sendTimeout :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_SNDTIMEO.

tcpKeepAlive :: Socket a -> IO Switch Source

zmq_getsockopt ZMQ_TCP_KEEPALIVE.

tcpKeepAliveCount :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_TCP_KEEPALIVE_CNT.

tcpKeepAliveIdle :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_TCP_KEEPALIVE_IDLE.

tcpKeepAliveInterval :: Socket a -> IO Int Source

zmq_getsockopt ZMQ_TCP_KEEPALIVE_INTVL.

zapDomain :: Socket a -> IO ByteString Source

zmq_getsockopt ZMQ_ZAP_DOMAIN.

Socket Options (Write)

setAffinity :: Word64 -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_AFFINITY.

setBacklog :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_BACKLOG.

setConflate :: Conflatable a => Bool -> Socket a -> IO ()Source

Restrict the outgoing and incoming socket buffers to a single message.

setCurveServer :: Bool -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_CURVE_SERVER.

setCurvePublicKey :: KeyFormat f -> Restricted f ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_CURVE_PUBLICKEY.

setCurveSecretKey :: KeyFormat f -> Restricted f ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_CURVE_SECRETKEY.

setCurveServerKey :: KeyFormat f -> Restricted f ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_CURVE_SERVERKEY.

setDelayAttachOnConnect :: Bool -> Socket a -> IO ()Source

Deprecated: Use setImmediate

setIdentity :: Restricted (N1, N254) ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_IDENTITY.

setImmediate :: Bool -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_IMMEDIATE.

setIpv4Only :: Bool -> Socket a -> IO ()Source

Deprecated: Use setIpv6

setIpv6 :: Bool -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_IPV6.

setLinger :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_LINGER.

setMaxMessageSize :: Integral i => Restricted (Nneg1, Int64) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_MAXMSGSIZE.

setMcastHops :: Integral i => Restricted (N1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_MULTICAST_HOPS.

setPlainServer :: Bool -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_PLAIN_SERVER.

setPlainPassword :: Restricted (N1, N254) ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_PLAIN_USERNAME.

setPlainUserName :: Restricted (N1, N254) ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_PLAIN_USERNAME.

setProbeRouter :: SendProbe a => Bool -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_PROBE_ROUTER.

setRate :: Integral i => Restricted (N1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RATE.

setReceiveBuffer :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RCVBUF.

setReceiveHighWM :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RCVHWM.

setReceiveTimeout :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RCVTIMEO.

setReconnectInterval :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RECONNECT_IVL.

setReconnectIntervalMax :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RECONNECT_IVL_MAX.

setRecoveryInterval :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_RECOVERY_IVL.

setReqCorrelate :: Bool -> Socket Req -> IO ()Source

zmq_setsockopt ZMQ_REQ_CORRELATE.

setReqRelaxed :: Bool -> Socket Req -> IO ()Source

zmq_setsockopt ZMQ_REQ_RELAXED.

setRouterMandatory :: Bool -> Socket Router -> IO ()Source

zmq_setsockopt ZMQ_ROUTER_MANDATORY.

setSendBuffer :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_SNDBUF.

setSendHighWM :: Integral i => Restricted (N0, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_SNDHWM.

setSendTimeout :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_SNDTIMEO.

setTcpAcceptFilter :: Maybe ByteString -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_TCP_ACCEPT_FILTER.

setTcpKeepAlive :: Switch -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_TCP_KEEPALIVE.

setTcpKeepAliveCount :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_TCP_KEEPALIVE_CNT.

setTcpKeepAliveIdle :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_TCP_KEEPALIVE_IDLE.

setTcpKeepAliveInterval :: Integral i => Restricted (Nneg1, Int32) i -> Socket a -> IO ()Source

zmq_setsockopt ZMQ_TCP_KEEPALIVE_INTVL.

setXPubVerbose :: Bool -> Socket XPub -> IO ()Source

zmq_setsockopt ZMQ_XPUB_VERBOSE.

Restrictions

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

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)Source

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

Error Handling

data ZMQError Source

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
Typeable ZMQError
Exception ZMQError

errno :: ZMQError -> Int Source

Error number value.

source :: ZMQError -> String Source

Source where this error originates from.

message :: ZMQError -> String Source

Actual error message.

Low-level Functions

init :: Size -> IO Context Source

Deprecated: Use context

term :: Context -> IO ()Source

Terminate a 0MQ context. Equivalent to zmq_ctx_term.

shutdown :: Context -> IO ()Source

Shutdown a 0MQ context. Equivalent to zmq_ctx_shutdown.

context :: IO Context Source

Initialize a 0MQ context. Equivalent to zmq_ctx_new.

socket :: SocketType a => Context -> a -> IO (Socket a)Source

Create a new 0MQ socket within the given context. withSocket provides automatic socket closing and may be safer to use.

close :: Socket a -> IO ()Source

Close a 0MQ socket. withSocket provides automatic socket closing and may be safer to use.

waitRead :: Socket a -> IO ()Source

Wait until data is available for reading from the given Socket. After this function returns, a call to receive will essentially be non-blocking.

waitWrite :: Socket a -> IO ()Source

Wait until data can be written to the given Socket. After this function returns, a call to send will essentially be non-blocking.

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

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

Utils

proxy :: Socket a -> Socket b -> Maybe (Socket c) -> IO ()Source

Starts built-in 0MQ proxy (cf. zmq_proxy)

Proxy connects front to back socket

Before calling proxy all sockets should be binded

If the capture socket is not Nothing, the proxy shall send all messages, received on both frontend and backend, to the capture socket.

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

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