Home
Ratchet Library :: ZeroMQ Sockets
API  ·  Manual

ratchet.zmqsocket API Reference

Creation

For applications that need more advanced and fool-proof messaging than regular sockets can provide, ZeroMQ sockets are available in the ratchet.zmqsocket library. This is a relatively generic exposure of ZeroMQ sockets, so for more details on how they work please see the ZeroMQ website and documentation.

If ZeroMQ is compiled in and the ratchet library is loaded with a basic require "ratchet" or require "ratchet.zmqsocket" then a ZeroMQ context is created automatically for any and all ZeroMQ sockets created, regardless of ratchet object. The context is cleaned up as garbage at termination, its existence is hidden from the ratchet library's usage.

To create a new zmqsocket, use the constructor ratchet.zmqsocket.new() with a string representing what type of socket wanted. The string should be an upper-case version of the socket types listed here after the "ZMQ_" prefix, e.g. "PAIR" (default), or "REQ".

require "ratchet.zmqsocket"

local zsock = ratchet.zmqsocket.new("PUB")

Connect / Listen

Once you have a zmqsocket object, it needs to either connect to a server or open itself to conections.

To connect to a server, use zmqsocket:connect() with a string that defines the endpoint to connect to, as described in the endpoint argument of the zmq_connect(3) man page. The connection actually only happens as needed, so this call always returns true.

zsock1:connect("inproc://#1")

To listen for connections, use zmqsocket:bind() with a string that defines the endpoint to listen on, as described in the endpoint argument of the zmq_bind(3) man page. There is no need to make any other calls, bind() on a zmqsocket object does what both bind() and listen() do on a normal socket.

zsock2:bind("inproc://#1")

Communication

Once a zmqsocket has established itself as connecting or listening, it is ready to send and receive data. The behavior of sending and receiving is controlled by the socket type and should be carefully observed.

Send

To send a message (or message part), make a call to zmqsocket:send() with a string of data. This will pause the current thread until it can safely send without blocking.

zsock:send("hello world")

Recv

To receive a message (or message part), make a call to zmqsocket:recv() which will return a string of data. This will pause the current thread until data is available to receive.

local data = zsock:recv()
assert(data == "hello world")

Multi-part Messages

Every send and receive in ZeroMQ is actually a multi-part message of one or more parts, but the ratchet library defaults to and makes it easiest for one part. To send a multi-part message, simply call send() with a second boolean true argument for each message part until the final one.

zsock:send("hello world", true)
zsock:send(" my name is ratchet")

To receive each message part, simply call recv() as usual, but pay attention to the second returned value, which is true if more message parts are yet to be recv()'ed. The final message part will have false as the second returned value.

repeat
    local datapart, more = zsock:recv()
    print(datapart)
until not more

Finally, if the division of the message parts is not important, there is a convenience method zmqsocket:recv_all() that will receive call recv() until no more message parts are available and returns a concatenated version of all parts in order.

local data = zsock:recv_all()
assert(data == "hello world my name is ratchet")

Timeouts

By default, zmqsocket methods that pause the thread will do so indefinitely until the the action is taken successfully. This is rarely desirable in the real world, as a bad remote host could indefinitely consume valuable server resources. With timeouts, unsuccessful calls will unpause the thread after a certain number of seconds. To set the timeout for all zmqsocket methods that pause, use zmqsocket:set_timeout() with a floating-point number of seconds. To get the current timeout setting, use zmqsocket:get_timeout(). If you need different timeouts for different zmqsocket methods, you must call set_timeout() every time it must be changed.

zsock:set_timeout(10.0)
local data = zsock:recv()   -- may raise an error after 10 seconds

URI Parsing

The zmqsocket library provides a function to parse URI strings containing everything you need to know about a ZMQ socket. URIs are expected in the following form:

  • zmq:TYPE:ENDPOINT

The TYPE and ENDPOINT placeholders correspond to the different ZMQ socket types and the exact string to pass in to the bind() or connect() methods.

The result is a table with the keys "type" and "endpoint". The "type" key has been pre-converted into upper-case, as that is how the constructor expects it.

local rec = ratchet.zmqsocket.prepare_uri("zmq:pull:tcp://*:1337")
local zsock = ratchet.zmqsocket.new(rec.type)
zsock:bind(rec.endpoint)



Last modified:  Sun, 17 Aug 2014 09:32:32 -0400
Author:  ian.good