zeromq4-haskell-0.6.7: Bindings to ZeroMQ 4.x

Copyright(c) 2010-2013 Toralf Wittner
LicenseMIT
MaintainerToralf Wittner <tw@dtex.org>
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell98

System.ZMQ4

Contents

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 #

Constructors

Pair 

Instances

Eq Pair # 

Methods

(==) :: Pair -> Pair -> Bool #

(/=) :: Pair -> Pair -> Bool #

Generic Pair # 

Associated Types

type Rep Pair :: * -> * #

Methods

from :: Pair -> Rep Pair x #

to :: Rep Pair x -> Pair #

SocketType Pair # 
Receiver Pair # 
Sender Pair # 
type Rep Pair # 
type Rep Pair = D1 (MetaData "Pair" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Pair" PrefixI False) U1)

data Pub #

Constructors

Pub 

Instances

Eq Pub # 

Methods

(==) :: Pub -> Pub -> Bool #

(/=) :: Pub -> Pub -> Bool #

Generic Pub # 

Associated Types

type Rep Pub :: * -> * #

Methods

from :: Pub -> Rep Pub x #

to :: Rep Pub x -> Pub #

SocketType Pub # 
Conflatable Pub # 
Sender Pub # 
type Rep Pub # 
type Rep Pub = D1 (MetaData "Pub" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Pub" PrefixI False) U1)

data Sub #

Constructors

Sub 

Instances

Eq Sub # 

Methods

(==) :: Sub -> Sub -> Bool #

(/=) :: Sub -> Sub -> Bool #

Generic Sub # 

Associated Types

type Rep Sub :: * -> * #

Methods

from :: Sub -> Rep Sub x #

to :: Rep Sub x -> Sub #

SocketType Sub # 
Conflatable Sub # 
Receiver Sub # 
Subscriber Sub # 
type Rep Sub # 
type Rep Sub = D1 (MetaData "Sub" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Sub" PrefixI False) U1)

data XPub #

Constructors

XPub 

Instances

Eq XPub # 

Methods

(==) :: XPub -> XPub -> Bool #

(/=) :: XPub -> XPub -> Bool #

Generic XPub # 

Associated Types

type Rep XPub :: * -> * #

Methods

from :: XPub -> Rep XPub x #

to :: Rep XPub x -> XPub #

SocketType XPub # 
Receiver XPub # 
Sender XPub # 
type Rep XPub # 
type Rep XPub = D1 (MetaData "XPub" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "XPub" PrefixI False) U1)

data XSub #

Constructors

XSub 

Instances

Eq XSub # 

Methods

(==) :: XSub -> XSub -> Bool #

(/=) :: XSub -> XSub -> Bool #

Generic XSub # 

Associated Types

type Rep XSub :: * -> * #

Methods

from :: XSub -> Rep XSub x #

to :: Rep XSub x -> XSub #

SocketType XSub # 
Receiver XSub # 
Sender XSub # 
type Rep XSub # 
type Rep XSub = D1 (MetaData "XSub" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "XSub" PrefixI False) U1)

data Req #

Constructors

Req 

Instances

Eq Req # 

Methods

(==) :: Req -> Req -> Bool #

(/=) :: Req -> Req -> Bool #

Generic Req # 

Associated Types

type Rep Req :: * -> * #

Methods

from :: Req -> Rep Req x #

to :: Rep Req x -> Req #

SocketType Req # 
SendProbe Req # 
Receiver Req # 
Sender Req # 
type Rep Req # 
type Rep Req = D1 (MetaData "Req" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Req" PrefixI False) U1)

data Rep #

Constructors

Rep 

Instances

Eq Rep # 

Methods

(==) :: Rep -> Rep -> Bool #

(/=) :: Rep -> Rep -> Bool #

Generic Rep # 

Associated Types

type Rep Rep :: * -> * #

Methods

from :: Rep -> Rep Rep x #

to :: Rep Rep x -> Rep #

SocketType Rep # 
Receiver Rep # 
Sender Rep # 
type Rep Rep # 
type Rep Rep = D1 (MetaData "Rep" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Rep" PrefixI False) U1)

data Dealer #

Constructors

Dealer 

Instances

Eq Dealer # 

Methods

(==) :: Dealer -> Dealer -> Bool #

(/=) :: Dealer -> Dealer -> Bool #

Generic Dealer # 

Associated Types

type Rep Dealer :: * -> * #

Methods

from :: Dealer -> Rep Dealer x #

to :: Rep Dealer x -> Dealer #

SocketType Dealer # 
SendProbe Dealer # 
Conflatable Dealer # 
Receiver Dealer # 
Sender Dealer # 
type Rep Dealer # 
type Rep Dealer = D1 (MetaData "Dealer" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Dealer" PrefixI False) U1)

data Router #

Constructors

Router 

Instances

Eq Router # 

Methods

(==) :: Router -> Router -> Bool #

(/=) :: Router -> Router -> Bool #

Generic Router # 

Associated Types

type Rep Router :: * -> * #

Methods

from :: Router -> Rep Router x #

to :: Rep Router x -> Router #

SocketType Router # 
SendProbe Router # 
Receiver Router # 
Sender Router # 
type Rep Router # 
type Rep Router = D1 (MetaData "Router" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Router" PrefixI False) U1)

type XReq = Dealer #

Deprecated: Use Dealer

type XRep = Router #

Deprecated: Use Router

data Pull #

Constructors

Pull 

Instances

Eq Pull # 

Methods

(==) :: Pull -> Pull -> Bool #

(/=) :: Pull -> Pull -> Bool #

Generic Pull # 

Associated Types

type Rep Pull :: * -> * #

Methods

from :: Pull -> Rep Pull x #

to :: Rep Pull x -> Pull #

SocketType Pull # 
Conflatable Pull # 
Receiver Pull # 
type Rep Pull # 
type Rep Pull = D1 (MetaData "Pull" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Pull" PrefixI False) U1)

data Push #

Constructors

Push 

Instances

Eq Push # 

Methods

(==) :: Push -> Push -> Bool #

(/=) :: Push -> Push -> Bool #

Generic Push # 

Associated Types

type Rep Push :: * -> * #

Methods

from :: Push -> Rep Push x #

to :: Rep Push x -> Push #

SocketType Push # 
Conflatable Push # 
Sender Push # 
type Rep Push # 
type Rep Push = D1 (MetaData "Push" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Push" PrefixI False) U1)

data Stream #

Constructors

Stream 

Instances

Eq Stream # 

Methods

(==) :: Stream -> Stream -> Bool #

(/=) :: Stream -> Stream -> Bool #

Generic Stream # 

Associated Types

type Rep Stream :: * -> * #

Methods

from :: Stream -> Rep Stream x #

to :: Rep Stream x -> Stream #

SocketType Stream # 
Receiver Stream # 
Sender Stream # 
type Rep Stream # 
type Rep Stream = D1 (MetaData "Stream" "System.ZMQ4" "zeromq4-haskell-0.6.7-L3WUeGqXgmHq3WFLUvcLE" False) (C1 (MetaCons "Stream" PrefixI False) U1)

Socket type-classes

class Sender a #

Sockets which can send.

class Subscriber a #

Sockets which can subscribe.

Instances

class SocketLike s #

Minimal complete definition

toSocket

Instances

SocketLike Socket # 

Methods

toSocket :: Socket t -> Socket t #

SocketLike (Socket z) # 

Methods

toSocket :: Socket z t -> Socket t #

class SendProbe a #

Sockets which can send probes (cf. setProbeRouter).

Various type definitions

type Size = Word #

data Context #

A 0MQ context representation.

data Socket a #

A 0MQ Socket.

Instances

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 # 

Methods

(==) :: Flag -> Flag -> Bool #

(/=) :: Flag -> Flag -> Bool #

Ord Flag # 

Methods

compare :: Flag -> Flag -> Ordering #

(<) :: Flag -> Flag -> Bool #

(<=) :: Flag -> Flag -> Bool #

(>) :: Flag -> Flag -> Bool #

(>=) :: Flag -> Flag -> Bool #

max :: Flag -> Flag -> Flag #

min :: Flag -> Flag -> Flag #

Show Flag # 

Methods

showsPrec :: Int -> Flag -> ShowS #

show :: Flag -> String #

showList :: [Flag] -> ShowS #

data Switch #

Configuration switch

Constructors

Default

Use default setting

On

Activate setting

Off

De-activate setting

Instances

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

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 #

Instances

Eq (KeyFormat a) # 

Methods

(==) :: KeyFormat a -> KeyFormat a -> Bool #

(/=) :: KeyFormat a -> KeyFormat a -> Bool #

Show (KeyFormat a) # 

General Operations

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

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 b #

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 () #

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

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

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

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

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

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

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

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

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 () #

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 () #

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 #

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] #

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

version :: IO (Int, Int, Int) #

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

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 () #

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]] #

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 () #

Subscribe Socket to given subscription.

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

Unsubscribe Socket from given subscription.

Context Options (Read)

Context Options (Write)

Socket Options (Read)

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

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

delayAttachOnConnect :: Socket a -> IO Bool #

Deprecated: Use immediate

ipv4Only :: Socket a -> IO Bool #

Deprecated: Use ipv6

Socket Options (Write)

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

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

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

Deprecated: Use setImmediate

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

Deprecated: Use setIpv6

Restrictions

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.

Error Handling

data ZMQError #

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

errno :: ZMQError -> Int #

Error number value.

source :: ZMQError -> String #

Source where this error originates from.

message :: ZMQError -> String #

Actual error message.

Low-level Functions

init :: Size -> IO Context #

Deprecated: Use context

term :: Context -> IO () #

Terminate a 0MQ context. Equivalent to zmq_ctx_term.

shutdown :: Context -> IO () #

Shutdown a 0MQ context. Equivalent to zmq_ctx_shutdown.

context :: IO Context #

Initialize a 0MQ context. Equivalent to zmq_ctx_new.

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

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

close :: Socket a -> IO () #

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

waitRead :: Socket a -> IO () #

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 () #

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

Utils

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

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

Proxy connects front to back socket

Before calling proxy all sockets should be bound

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

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