Portability	non-portable
Stability	experimental
Maintainer	toralf.wittner@gmail.com

System.ZMQ

Contents

Low-level functions

Description

0MQ haskell binding. The API closely follows the C-API of 0MQ with the main difference that sockets are typed. The documentation of the individual socket types and socket options is copied from 0MQ's man pages authored by Martin Sustrik.

Synopsis

Documentation

type Size = Word Source

data Context Source

A 0MQ context representation.

data Socket a Source

A 0MQ Socket.

data Flag Source

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

NoBlock: Send operation should be performed in non-blocking mode. If it cannot be performed immediatley an error will be thrown (errno is set to EAGAIN).

Constructors

NoBlock	ZMQ_NOBLOCK
SndMore	ZMQ_SNDMORE

Instances

Eq Flag
Ord Flag
Show Flag

data SocketOption Source

The option to set on 0MQ sockets (descriptions reproduced here from zmq_setsockopt(3) (cf. man zmq_setsockopt for further details)).

HighWM: High watermark for the message pipes associated with the socket. The water mark cannot be exceeded. If the messages don't fit into the pipe emergency mechanisms of the particular socket type are used (block, drop etc.) If HWM is set to zero, there are no limits for the content of the pipe. Default: 0
Swap: Swap allows the pipe to exceed high watermark. However, the data are written to the disk rather than held in the memory. Until high watermark is exceeded there is no disk activity involved though. The value of the option defines maximal size of the swap file. Default: 0
Affinity: Affinity defines which threads in the thread pool will be used to handle newly created sockets. This way you can dedicate some of the threads (CPUs) to a specific work. Value of 0 means no affinity. Work is distributed fairly among the threads in the thread pool. For non-zero values, the lowest bit corresponds to the thread 1, second lowest bit to the thread 2 etc. Thus, value of 3 means that from now on newly created sockets will handle I/O activity exclusively using threads no. 1 and 2. Default: 0
Identity: Identity of the socket. Identity is important when restarting applications. If the socket has no identity, each run of the application is completely separated from other runs. However, with identity application reconnects to existing infrastructure left by the previous run. Thus it may receive messages that were sent in the meantime, it shares pipe limits with the previous run etc. Default: NULL
Rate: This option applies only to sending side of multicast transports (pgm & udp). It specifies maximal outgoing data rate that an individual sender socket can send. Default: 100
RecoveryIVL: This option applies only to multicast transports (pgm & udp). It specifies how long can the receiver socket survive when the sender is inaccessible. Keep in mind that large recovery intervals at high data rates result in very large recovery buffers, meaning that you can easily overload your box by setting say 1 minute recovery interval at 1Gb/s rate (requires 7GB in-memory buffer). Default: 10
McastLoop: This option applies only to multicast transports (pgm & udp). Value of 1 means that the mutlicast packets can be received on the box they were sent from. Setting the value to 0 disables the loopback functionality which can have negative impact on the performance. If possible, disable the loopback in production environments. Default: 1
SendBuf: Sets the underlying kernel transmit buffer size to the specified size. See SO_SNDBUF POSIX socket option. Value of zero means leaving the OS default unchanged. Default: 0
ReceiveBuf: Sets the underlying kernel receive buffer size to the specified size. See SO_RCVBUF POSIX socket option. Value of zero means leaving the OS default unchanged. Default: 0

Constructors

HighWM Word64	ZMQ_HWM
Swap Int64	ZMQ_SWAP
Affinity Word64	ZMQ_AFFINITY
Identity String	ZMQ_IDENTITY
Rate Int64	ZMQ_RATE
RecoveryIVL Int64	ZMQ_RECOVERY_IVL
RecoveryIVLMsec Int64	ZMQ_RECOVERY_IVL_MSEC
McastLoop Int64	ZMQ_MCAST_LOOP
SendBuf Word64	ZMQ_SNDBUF
ReceiveBuf Word64	ZMQ_RCVBUF
FD CInt	ZMQ_FD
Events Word32	ZMQ_EVENTS
Linger CInt	ZMQ_LINGER
ReconnectIVL CInt	ZMQ_RECONNECT_IVL
Backlog CInt	ZMQ_BACKLOG

Instances

Eq SocketOption
Ord SocketOption
Show SocketOption

data Poll Source

Type representing a descriptor, poll is waiting for (either a 0MQ socket or a file descriptor) plus the type of event to wait for.

Constructors

forall a . S (Socket a) PollEvent
F Fd PollEvent

type Timeout = Int64 Source

data PollEvent Source

The events to wait for in poll (cf. man zmq_poll)

Constructors

In	ZMQ_POLLIN (incoming messages)
Out	ZMQ_POLLOUT (outgoing messages, i.e. at least 1 byte can be written)
InOut	ZMQ_POLLIN \| ZMQ_POLLOUT
Native	ZMQ_POLLERR

Instances

Eq PollEvent
Ord PollEvent
Show PollEvent

data Device Source

Type representing ZeroMQ devices, as used with zmq_device

Constructors

Streamer	ZMQ_STREAMER
Forwarder	ZMQ_FORWARDER
Queue	ZMQ_QUEUE

Instances

Eq Device
Ord Device
Show Device

class SType a Source

Instances

SType Down
SType Up
SType Push
SType Pull
SType XRep
SType XReq
SType Rep
SType Req
SType Sub
SType Pub
SType Pair

class SubsType a Source

Instances

SubsType Sub

data Pair Source

Socket to communicate with a single peer. Allows for only a single connect or a single bind. There's no message routing or message filtering involved. Compatible peer sockets: Pair.

Constructors

Pair

Instances

SType Pair

data Pub Source

Socket to distribute data. receive function is not implemented for this socket type. Messages are distributed in fanout fashion to all the peers. Compatible peer sockets: Sub.

Constructors

Pub

Instances

SType Pub

data Sub Source

Socket to subscribe for data. Send function is not implemented for this socket type. Initially, socket is subscribed for no messages. Use subscribe to specify which messages to subscribe for. Compatible peer sockets: Pub.

Constructors

Sub

Instances

SubsType Sub
SType Sub

data Req Source

Socket to send requests and receive replies. Requests are load-balanced among all the peers. This socket type allows only an alternated sequence of send's and recv's. Compatible peer sockets: Rep, Xrep.

Constructors

Req

Instances

SType Req

data Rep Source

Socket to receive requests and send replies. This socket type allows only an alternated sequence of receive's and send's. Each send is routed to the peer that issued the last received request. Compatible peer sockets: Req, XReq.

Constructors

Rep

Instances

SType Rep

data XReq Source

Special socket type to be used in request/reply middleboxes such as zmq_queue(7). Requests forwarded using this socket type should be tagged by a proper prefix identifying the original requester. Replies received by this socket are tagged with a proper postfix that can be use to route the reply back to the original requester. Compatible peer sockets: Rep, Xrep.

Constructors

Xreq

Instances

SType XReq

data XRep Source

Special socket type to be used in request/reply middleboxes such as zmq_queue(7). Requests received using this socket are already properly tagged with prefix identifying the original requester. When sending a reply via XREP socket the message should be tagged with a prefix from a corresponding request. Compatible peer sockets: Req, Xreq.

Constructors

Xrep

Instances

SType XRep

data Pull Source

A socket of type ZMQ_PULL is used by a pipeline node to receive messages from upstream pipeline nodes. Messages are fair-queued from among all connected upstream nodes. The zmq_send() function is not implemented for this socket type.

Constructors

Pull

Instances

SType Pull

data Push Source

A socket of type ZMQ_PUSH is used by a pipeline node to send messages to downstream pipeline nodes. Messages are load-balanced to all connected downstream nodes. The zmq_recv() function is not implemented for this socket type.

When a ZMQ_PUSH socket enters an exceptional state due to having reached the high water mark for all downstream nodes, or if there are no downstream nodes at all, then any zmq_send(3) operations on the socket shall block until the exceptional state ends or at least one downstream node becomes available for sending; messages are not discarded.

Constructors

Push

Instances

SType Push

data Up Source

Socket to receive messages from up the stream. Messages are fair-queued from among all the connected peers. Send function is not implemented for this socket type. Compatible peer sockets: Down.

Constructors

Up

Instances

SType Up

data Down Source

Socket to send messages down stream. Messages are load-balanced among all the connected peers. Send function is not implemented for this socket type. Compatible peer sockets: Up.

Constructors

Down

Instances

SType Down

withContext :: Size -> (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 :: SType 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.

setOption :: Socket a -> SocketOption -> IO ()Source

Set the given option on the socket. Please note that there are certain combatibility constraints w.r.t the socket type (cf. man zmq_setsockopt).

Please note that subscribe/unsubscribe is handled with separate functions.

getOption :: Socket a -> SocketOption -> IO SocketOption Source

Get the given socket option by passing in some dummy value of that option. The actual value will be returned. Please note that there are certain combatibility constraints w.r.t the socket type (cf. man zmq_setsockopt).

subscribe :: SubsType a => Socket a -> String -> IO ()Source

Subscribe Socket to given subscription.

unsubscribe :: SubsType a => Socket a -> String -> IO ()Source

Unsubscribe Socket from given subscription.

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

Bind the socket to the given address (zmq_bind)

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

Connect the socket to the given address (zmq_connect).

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

Send the given ByteString over the socket (zmq_send).

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

Send the given ByteString over the socket (zmq_send). This is operationally identical to send socket (Strict.concat (Lazy.toChunks lbs)) flags but may be more efficient.

receive :: Socket a -> [Flag] -> IO ByteString Source

Receive a ByteString from socket (zmq_recv).

moreToReceive :: Socket a -> IO Bool Source

Equivalent of ZMQ_RCVMORE, i.e. returns True if a multi-part message currently being read has more parts to follow, otherwise False.

poll :: [Poll] -> Timeout -> IO [Poll]Source

Polls for events on the given Poll descriptors. Returns the list of Poll descriptors for which an event occured (cf. zmq_poll).

device :: Device -> Socket a -> Socket b -> IO ()Source

Launch a ZeroMQ device (zmq_device).

Please note that this call never returns.

Low-level functions

init :: Size -> IO Context Source

Initialize a 0MQ context (cf. zmq_init for details). You should normally prefer to use with instead.

term :: Context -> IO ()Source

Terminate a 0MQ context (cf. zmq_term). You should normally prefer to use with instead.

socket :: SType 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.