-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Bindings to ZeroMQ 2.1.x
--   
--   The 0MQ lightweight messaging kernel is a library which extends the
--   standard socket interfaces with features traditionally provided by
--   specialised messaging middleware products. 0MQ sockets provide an
--   abstraction of asynchronous message queues, multiple messaging
--   patterns, message filtering (subscriptions), seamless access to
--   multiple transport protocols and more. This library provides the
--   Haskell language binding to 0MQ and supports 0MQ 2.1.x.
@package zeromq-haskell
@version 0.8.4


-- | 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 is copied from 0MQ's man pages authored by
--   Martin Sustrik. For details please refer to http:<i></i>api.zeromq.org
module System.ZMQ
type Size = Word

-- | A 0MQ context representation.
data Context

-- | A 0MQ Socket.
data Socket a

-- | Flags to apply on send operations (cf. man zmq_send)
--   
--   <ul>
--   <li><i><tt>NoBlock</tt></i> 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).</li>
--   </ul>
data Flag

-- | ZMQ_NOBLOCK (0MQ-2.x), ZMQ_DONTWAIT (0MQ-3.x)
NoBlock :: Flag

-- | ZMQ_SNDMORE
SndMore :: Flag

-- | The option to set on 0MQ sockets (cf. zmq_setsockopt and
--   zmq_getsockopt manpages for details).
data SocketOption

-- | ZMQ_AFFINITY
Affinity :: Word64 -> SocketOption

-- | ZMQ_BACKLOG
Backlog :: CInt -> SocketOption

-- | ZMQ_EVENTS
Events :: PollEvent -> SocketOption

-- | ZMQ_FD
FD :: CInt -> SocketOption

-- | ZMQ_IDENTITY
Identity :: String -> SocketOption

-- | ZMQ_LINGER
Linger :: CInt -> SocketOption

-- | ZMQ_RATE
Rate :: Int64 -> SocketOption

-- | ZMQ_RCVBUF
ReceiveBuf :: Word64 -> SocketOption

-- | ZMQ_RCVMORE
ReceiveMore :: Bool -> SocketOption

-- | ZMQ_RECONNECT_IVL
ReconnectIVL :: CInt -> SocketOption

-- | ZMQ_RECONNECT_IVL_MAX
ReconnectIVLMax :: CInt -> SocketOption

-- | ZMQ_RECOVERY_IVL
RecoveryIVL :: Int64 -> SocketOption

-- | ZMQ_SNDBUF
SendBuf :: Word64 -> SocketOption

-- | ZMQ_HWM
HighWM :: Word64 -> SocketOption

-- | ZMQ_MCAST_LOOP
McastLoop :: Bool -> SocketOption

-- | ZMQ_RECOVERY_IVL_MSEC
RecoveryIVLMsec :: Int64 -> SocketOption

-- | ZMQ_SWAP
Swap :: Int64 -> SocketOption

-- | Type representing a descriptor, poll is waiting for (either a 0MQ
--   socket or a file descriptor) plus the type of event to wait for.
data Poll
S :: (Socket a) -> PollEvent -> Poll
F :: Fd -> PollEvent -> Poll
type Timeout = Int64

-- | The events to wait for in poll (cf. man zmq_poll)
data PollEvent

-- | ZMQ_POLLIN (incoming messages)
In :: PollEvent

-- | ZMQ_POLLOUT (outgoing messages, i.e. at least 1 byte can be written)
Out :: PollEvent

-- | ZMQ_POLLIN | ZMQ_POLLOUT
InOut :: PollEvent

-- | ZMQ_POLLERR
Native :: PollEvent
None :: PollEvent

-- | Socket types.
class SType a

-- | Subscribable.
class SubsType a

-- | 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. <i>Compatible peer sockets</i>: <a>Pair</a>.
data Pair
Pair :: Pair

-- | Socket to distribute data. <a>receive</a> function is not implemented
--   for this socket type. Messages are distributed in fanout fashion to
--   all the peers. <i>Compatible peer sockets</i>: <a>Sub</a>.
data Pub
Pub :: Pub

-- | Socket to subscribe for data. Send function is not implemented for
--   this socket type. Initially, socket is subscribed for no messages. Use
--   <a>subscribe</a> to specify which messages to subscribe for.
--   <i>Compatible peer sockets</i>: <a>Pub</a>.
data Sub
Sub :: Sub

-- | 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. <i>Compatible peer
--   sockets</i>: <a>Rep</a>, <tt>Xrep</tt>.
data Req
Req :: Req

-- | 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.
--   <i>Compatible peer sockets</i>: <a>Req</a>, <a>XReq</a>.
data Rep
Rep :: Rep

-- | 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. <i>Compatible
--   peer sockets</i>: <a>Rep</a>, <tt>Xrep</tt>.
data XReq
XReq :: XReq

-- | 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. <i>Compatible peer sockets</i>: <a>Req</a>,
--   <tt>Xreq</tt>.
data XRep
XRep :: XRep
data Dealer
Dealer :: Dealer
data Router
Router :: Router

-- | A socket of type 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.
data Pull
Pull :: Pull

-- | A socket of type 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 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.
data Push
Push :: Push

-- | 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. <i>Compatible peer sockets</i>:
--   <a>Down</a>.

-- | <i>Deprecated: Use Pull instead. </i>
data Up

-- | <i>Deprecated: Use Pull instead. </i>
Up :: Up

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

-- | <i>Deprecated: Use Push instead. </i>
data Down

-- | <i>Deprecated: Use Push instead. </i>
Down :: Down

-- | Run an action with a 0MQ context. The <a>Context</a> supplied to your
--   action will <i>not</i> be valid after the action either returns or
--   throws an exception.
withContext :: Size -> (Context -> IO a) -> IO a

-- | 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 <i>not</i> be valid after the action
--   terminates.
withSocket :: SType a => Context -> a -> (Socket a -> IO b) -> IO b

-- | 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.
setOption :: Socket a -> SocketOption -> IO ()

-- | 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).
getOption :: Socket a -> SocketOption -> IO SocketOption

-- | Subscribe Socket to given subscription.
subscribe :: SubsType a => Socket a -> String -> IO ()

-- | Unsubscribe Socket from given subscription.
unsubscribe :: SubsType a => Socket a -> String -> IO ()

-- | Bind the socket to the given address (zmq_bind)
bind :: Socket a -> String -> IO ()

-- | Connect the socket to the given address (zmq_connect).
connect :: Socket a -> String -> IO ()

-- | Send the given <a>ByteString</a> over the socket (zmq_send).
send :: Socket a -> ByteString -> [Flag] -> IO ()

-- | Send the given <a>ByteString</a> over the socket (zmq_send). This is
--   operationally identical to <tt>send socket (Strict.concat
--   (Lazy.toChunks lbs)) flags</tt> but may be more efficient.
send' :: Socket a -> ByteString -> [Flag] -> IO ()

-- | Receive a <tt>ByteString</tt> from socket (zmq_recv).
receive :: Socket a -> [Flag] -> IO (ByteString)

-- | Equivalent of ZMQ_RCVMORE, i.e. returns True if a multi-part message
--   currently being read has more parts to follow, otherwise False.
moreToReceive :: Socket a -> IO Bool

-- | Polls for events on the given <a>Poll</a> descriptors. Returns the
--   same list of <a>Poll</a> descriptors with an <a>updated</a>
--   <a>PollEvent</a> field (cf. zmq_poll). Sockets which have seen no
--   activity have <a>None</a> in their <a>PollEvent</a> field.
poll :: [Poll] -> Timeout -> IO [Poll]
version :: IO (Int, Int, Int)

-- | Initialize a 0MQ context (cf. zmq_init for details). You should
--   normally prefer to use <a>with</a> instead.
init :: Size -> IO Context

-- | Terminate a 0MQ context (cf. zmq_term). You should normally prefer to
--   use <a>with</a> instead.
term :: Context -> IO ()

-- | Create a new 0MQ socket within the given context. <a>withSocket</a>
--   provides automatic socket closing and may be safer to use.
socket :: SType a => Context -> a -> IO (Socket a)

-- | Close a 0MQ socket. <a>withSocket</a> provides automatic socket
--   closing and may be safer to use.
close :: Socket a -> IO ()

-- | Type representing ZeroMQ devices, as used with zmq_device
data Device

-- | ZMQ_STREAMER
Streamer :: Device

-- | ZMQ_FORWARDER
Forwarder :: Device

-- | ZMQ_QUEUE
Queue :: Device

-- | Launch a ZeroMQ device (zmq_device).
--   
--   Please note that this call never returns.
device :: Device -> Socket a -> Socket b -> IO ()
instance Eq PollEvent
instance Ord PollEvent
instance Show PollEvent
instance Read PollEvent
instance Eq SocketOption
instance Ord SocketOption
instance Show SocketOption
instance Read SocketOption
instance Eq Device
instance Ord Device
instance Show Device
instance SubsType Sub
instance SType Down
instance SType Up
instance SType Push
instance SType Pull
instance SType Router
instance SType XRep
instance SType Dealer
instance SType XReq
instance SType Rep
instance SType Req
instance SType Sub
instance SType Pub
instance SType Pair
