ldoc

• Index

Contents

• Functions
• Class error
• Class context
• Class socket
• Class message

Modules

• lzmq.loop
• lzmq.poller
• lzmq.threads
• lzmq.timer
• lzmq

Module lzmq

lzmq is the Lua bindings for ZeroMQ.

lzmq supports ZMQ >=3.2.2, >=4.0.0.

Constants

ZMQ_CONSTANT_NAME in the C API turns into zmq.CONSTANT_NAME in Lua.

Error codes

EXXX in the C API turns into zmq.EXXX and zmq.errors.EXXX in Lua.

Options

ZMQ_OPTION_NAME in the C API:

• if this is read/write option then it turns into 2 functions `obj:set_option_name(value)` and `obj:get_option_name()`
  For example:
  ZMQ_IO_THREADS => ctx:get_io_threads()/ ctx:set_io_threads(1)
  
• if this is readonly option then it turns into 2 functions `obj:option_name()` and `obj:get_option_name()`
  For example:
  ZMQ_FD => skt:fd() / skt:get_fd()
• if this is writeonly option then it turns into 2 functions `obj:option_name(value)` and `obj:set_option_name(value)`
  For example:
  ZMQ_SUBSCRIBE => skt:subscribe("") / skt:set_subscribe("")

Functions

version ([unpack=false])	return the version of libzmq as a array
context ([options])	Create a zmq Context
init_ctx ()	Create a zmq Context based on Lua representation of zmq context pointer.
init_socket ()	Create a zmq Socket based on Lua representation of zmq socket pointer.
device (device, frontend, backend)	Create ZMQ Device
assert (...)	Raise error if condition is false.
error (errno)	Create new `error` object based on error number.
strerror (errno)	Get string description for errno.
msg_init ()	Create new `message` object.
msg_init_size (size)	Create new `message` object.
msg_init_data (source)	Create new `message` object.
proxy (frontend, backend[, capture])	Start built-in ZMQ proxy.
proxy_steerable (frontend, backend[, capture[, control]])	Start built-in ZMQ proxy with control.
z85_encode (src)	Encode a binary data as Z85 printable text.
z85_decode (src)	Decode a binary data from Z85 printable text.
curve_keypair ([binary=false])	Generate a new CURVE keypair.

Class error

error:no ()	Get the number value of error
error:mnemo ()	Get the error name
error:msg ()	Get the error description

Class context

context:destroy ([linger])	Close all sockets associated with this context, and then terminate the context.
context:term ()	This is alias for context:destroy
context:closed ()	Check if this Context has been terminated
context:get (option)	Get the value of a Context option.
context:set (option, value)	Set the value of a Context option.
context:lightuserdata ()	Get internal value of ZMQ Context as some Lua value.
context:socket_count ()	Return number of sockets associated with this context
context:shutdown ([linger])	Shutdown a zmq Context
context:shutdowned ()	Check if this Context has been shutdowned
context:socket (socket_type[, socket_options])	Create a Socket associated with this Context.
context:socket (socket_options)	Create a Socket associated with this Context.

Class socket

socket:close ([linger])	Close the socket
socket:closed ()	Check if this Socket has been closed.
socket:connect (address)	Connect Socket to a remote zmq Socket.
socket:connect (addresses)	Connect Socket to a remote zmq Sockets.
socket:disconnect (address)	Disconnect Socket from a remote zmq Socket.
socket:disconnect (addresses)	Disconnect Socket from a remote zmq Sockets.
socket:lightuserdata ()	Get internal value of ZMQ Socket as some Lua value.
socket:bind (address)	Bind Socket to a local address.
socket:bind (addresses)	Bind Socket to a local addresses.
socket:bind_to_random_port (address[, begin=0xC000[, number]])	Bind Socket to a local address and random port.
socket:unbind (address)	Unbind Socket from a local address.
socket:unbind (addresses)	Unbind Socket from a local addresses.
socket:poll ([timeout=-1[, events=zmq.POLLIN]])	Poll specific ZMQ Socket.
socket:send (message[, flags=0])	Send message over Socket.
socket:send_more (message[, flags=zmq.SNDMORE])	Send message over Socket.
socket:send_msg (message[, flags=0])	Send message over Socket.
socket:send_all (t[, flags=0[, begin_pos=1[, end_pos=#t]]])	Send a multipart message over Socket.
socket:send_multipart ()	This is alias for socket:send_all
socket:sendx (...)	Send a multipart message over Socket.
socket:sendx_more (...)	Send a multipart message over Socket.
socket:sendv (...)	Send a message over Socket.
socket:sendv_more (...)	Send a message over Socket.
socket:recv ([flags=0])	Receive a message.
socket:recv_len (len[, flags=0])	Receive first bytes from message.
socket:recv_msg (number[, flags=0])	Receive a message.
socket:recv_new_msg ([flags=0])	Receive a message.
socket:recv_all ([flags=0])	Receive multipart message.
socket:recv_multipart ()	This is alias for `socket:recv_all`
socket:recvx ([flags=0])	Receive multipart message.
socket:recv_event ([flags=0])	Receive zmq event message.
socket:monitor ([address[, enents=zmq.EVENT_ALL]])	Start publishing socket events on inproc.
socket:reset_monitor ()	Stop publishing socket events.
socket:has_event (mask)	Check if socket has specific event state.

Class message

message:close ()	Close message.
message:closed ()	Check if this Message has been closed.
message:move ()	Move current message to new one.
message:move (source)	Move source message to current one.
message:copy ()	Copy current message to new one.
message:copy (source)	Copy source message to current one.
message:size ()	Get size of message in bytes.
message:set_size (size)	Set size of message in bytes.
message:pointer ()	Get internal pointer to zmq_msg_t data.
message:data ()	Get data of message as string.
message:set_data ([position=1], data)	Set data of message.
message:more ()	Check if this message is not last in multipart message.
message:get (property)	Get ZMQ message property.
message:set (property, value)	Set ZMQ message property.
message:send (socket[, flags=0])	Send message.
message:send_more (socket[, flags=zmq.SNDMORE])	Send message.
message:recv (socket)	Receive message.

Functions

version ([unpack=false])

return the version of libzmq as a array

Parameters:

• unpack unpack zmq version (default false)

Returns:

{major,minor,patch} version of libzmq if unpack=false

Or

1. number major version of libzmq if unpack=true
2. number minor version of libzmq if unpack=true
3. number patch version of libzmq if unpack=true

context ([options])

Create a zmq Context This function ignores unknown options.

Parameters:

• options table {opt_name=opt_value, ...} map of options

Returns:

context new zmq context

Or

1. nil
2. error error object

Usage:

ctx = zmq.context{io_threads = 1, max_sockets = 255}

init_ctx ()

Create a zmq Context based on Lua representation of zmq context pointer.

For this context context:destroy does not call `zmq_ctx_term`.

Returns:

context new zmq Context

See also:

context:lightuserdata

init_socket ()

Create a zmq Socket based on Lua representation of zmq socket pointer.

For this socket socket:close does not call `zmq_close`.

Returns:

socket new zmq Socket

See also:

socket:lightuserdata

device (device, frontend, backend)

Create ZMQ Device

Parameters:

• device number type
• frontend socket
• backend socket

Returns:

1. nil
2. error

assert (...)

Raise error if condition is false. This function could work with `error` objects on Lua 5.1.

Parameters:

• ... ...

Returns:

...

error (errno)

Create new `error` object based on error number.

Parameters:

• errno number

Returns:

error error object

strerror (errno)

Get string description for errno.

Parameters:

• errno number

Returns:

string description

msg_init ()

Create new `message` object.

Returns:

message

msg_init_size (size)

Create new `message` object. This function allocate message to specific bytes.

Parameters:

• size number

Returns:

message

msg_init_data (source)

Create new `message` object. This function copy data to message from source string.

Parameters:

• source string

Returns:

message

proxy (frontend, backend[, capture])

Start built-in ZMQ proxy.

Parameters:

• frontend socket
• backend socket
• capture socket

Returns:

1. nil
2. error

proxy_steerable (frontend, backend[, capture[, control]])

Start built-in ZMQ proxy with control.

Parameters:

• frontend socket
• backend socket
• capture socket
• control socket

Returns:

1. nil
2. error

z85_encode (src)

Encode a binary data as Z85 printable text.

Parameters:

• src string

Returns:

string

z85_decode (src)

Decode a binary data from Z85 printable text.

Parameters:

• src string

Returns:

string

curve_keypair ([binary=false])

Generate a new CURVE keypair. This function avaliable only for ZeroMQ >= 4.0.1. Also you need build ZeroMQ with libsodium.

Parameters:

• binary bool if true thern keys return as binary string else they reuturn as Z85 encoded. (default false)

Returns:

1. string public key
2. string secret key

Class error

error:no ()

Get the number value of error

Returns:

number number of error (e.g. zmq.errors.ETERM).

error:mnemo ()

Get the error name

Returns:

string error name (e.g. "ETERM").

error:msg ()

Get the error description

Returns:

string result from `zmq_strerror`(e.g. "Context was terminated").

Class context

context:destroy ([linger])

Close all sockets associated with this context, and then terminate the context.

Parameters:

• linger number if present set zmq.LINGER option for socket before close it

Returns:

true

Or

1. nil
2. error

context:term ()

This is alias for context:destroy

context:closed ()

Check if this Context has been terminated

Returns:

bool true - you can no longer use this Context

context:get (option)

Get the value of a Context option.

Parameters:

• option number the option to get

Returns:

number the option value

Or

1. nil
2. error

Usage:

iot = ctx:get(zmq.IO_THREADS)

context:set (option, value)

Set the value of a Context option.

Parameters:

• option number the option to get
• value number the option value

Returns:

true

Or

1. nil
2. error

Usage:

ctx:set(zmq.MAX_SOCKETS, 255)

context:lightuserdata ()

Get internal value of ZMQ Context as some Lua value. You can use this value to pass a ZMQ Context to another lua_State.

Returns:

lightuserdata, string or number ZMQ Context.

See also:

lzmq.init_ctx

context:socket_count ()

Return number of sockets associated with this context

Returns:

number number of sockets

context:shutdown ([linger])

Shutdown a zmq Context

Parameters:

• linger number if present set zmq.LINGER option before shutdown

Returns:

true

Or

1. nil
2. error

context:shutdowned ()

Check if this Context has been shutdowned

Returns:

bool true - you can only destroy this Context

context:socket (socket_type[, socket_options])

Create a Socket associated with this Context. Ignores unknown options.

Parameters:

• socket_type number
• socket_options table {opt_name=opt_value,...}

Returns:

socket

Or

1. nil
2. error

Usage:

 skt = ctx:socket(zmq.PUB,{bind = {
    "tcp://*:5555";
    "ipc://test.pub.ipc";
 }})

context:socket (socket_options)

Create a Socket associated with this Context. Ignores unknown options.

Parameters:

• socket_options table {socket_type, opt_name=opt_value, ...}

Returns:

socket

Or

1. nil
2. error

Usage:

 skt = ctx:socket{zmq.SUB,
    subscribe = {"101:", "102:"};
    connect = "tcp://127.0.0.1:5555";
 }

Class socket

socket:close ([linger])

Close the socket

Parameters:

• linger number if present set zmq.LINGER option before close

Returns:

true

Or

1. nil
2. error

socket:closed ()

Check if this Socket has been closed.

Returns:

bool true - you can no longer use this Socket

socket:connect (address)

Connect Socket to a remote zmq Socket.

Parameters:

• address string zmq address

Returns:

true

Or

1. nil
2. error

Usage:

skt:connect("tcp://127.0.0.1:5555")

socket:connect (addresses)

Connect Socket to a remote zmq Sockets.

Parameters:

• addresses table {address, ...} array of zmq address

Returns:

true

Or

1. nil
2. error
3. string error address. Socket connected to previews addresses.

Usage:

skt:connect{"tcp://127.0.0.1:5555","ipc://test.pub.ipc"}

socket:disconnect (address)

Disconnect Socket from a remote zmq Socket.

Parameters:

• address string zmq address

Returns:

true

Or

1. nil
2. error

Usage:

skt:disconnect("tcp://127.0.0.1:5555")

socket:disconnect (addresses)

Disconnect Socket from a remote zmq Sockets.

Parameters:

• addresses table {address, ...} array of zmq address

Returns:

true

Or

1. nil
2. error
3. string error address. Socket disconnected from previews addresses.

Usage:

skt:disconnect{"tcp://127.0.0.1:5555","ipc://test.pub.ipc"}

socket:lightuserdata ()

Get internal value of ZMQ Socket as some Lua value. You can use this value to pass a ZMQ Socket to another lua_State.

Returns:

lightuserdata, string or number ZMQ Socket.

See also:

lzmq.init_socket

socket:bind (address)

Bind Socket to a local address.

Parameters:

• address string zmq address

Returns:

true

Or

1. nil
2. error

Usage:

skt:bind("tcp://*:5555")

socket:bind (addresses)

Bind Socket to a local addresses.

Parameters:

• addresses table {address, ...} array of zmq address

Returns:

true

Or

1. nil
2. error
3. string error address. Socket binded to previews addresses.

Usage:

skt:bind{"tcp://*:5555","ipc://test.pub.ipc"}

socket:bind_to_random_port (address[, begin=0xC000[, number]])

Bind Socket to a local address and random port.

Parameters:

• address string zmq address
• begin number port (default 0xC000)
• number number of tested ports. By default tests all ports up to 0xFFFF.

Returns:

number port number

Or

1. nil
2. error

Usage:

port = skt:bind_to_random_port("tcp://127.0.0.1")

socket:unbind (address)

Unbind Socket from a local address.

Parameters:

• address string zmq address

Returns:

true

Or

1. nil
2. error

Usage:

skt:unbind("tcp://*:5555")

socket:unbind (addresses)

Unbind Socket from a local addresses.

Parameters:

• addresses table {address, ...} array of zmq address

Returns:

true

Or

1. nil
2. error
3. string error address. Socket unbinded from previews addresses.

Usage:

skt:bind{"tcp://*:5555","ipc://test.pub.ipc"}

socket:poll ([timeout=-1[, events=zmq.POLLIN]])

Poll specific ZMQ Socket.

Parameters:

• timeout number timeout in milliseconds (-1 - infinity) (default -1)
• events number poll events. (default zmq.POLLIN)

Returns:

1. bool poll result (false if timeout)
2. number envents

Or

1. nil
2. error

Usage:

if skt:poll(100) then return skt:recv() end

socket:send (message[, flags=0])

Send message over Socket.

Parameters:

• message string content of message.
• flags number zmq send flags. (default 0)

Returns:

true

Or

1. nil
2. error

Usage:

 skt:send("Hello", zmq.SNDMORE)
 skt:send("World")

socket:send_more (message[, flags=zmq.SNDMORE])

Send message over Socket. This function always set flag zmq.SNDMORE to message

Parameters:

• message string content of message.
• flags number zmq send flags. (default zmq.SNDMORE)

Returns:

true

Or

1. nil
2. error

Usage:

 skt:send_more("Hello")
 skt:send_more("World", zmq.DONTWAIT) -- zmq.SNDMORE also setted

socket:send_msg (message[, flags=0])

Send message over Socket.

Parameters:

• message message content of message.
• flags number zmq send flags. (default 0)

Returns:

true

Or

1. nil
2. error

socket:send_all (t[, flags=0[, begin_pos=1[, end_pos=#t]]])

Send a multipart message over Socket. This function always set flag zmq.SNDMORE to message

Parameters:

• t table {string,...} parts of message.
• flags number zmq send flags. Support only zmq.SNDMORE flag. Any other flag cause error ENOTSUP. (default 0)
• begin_pos number position of first part in message (default 1)
• end_pos number position of last part in message (default #t)

Returns:

true

Or

1. nil
2. error
3. number index of error part

Raises:

"invalid internal"

Usage:

• skt:send_all{"Hello","World"}

• skt:send_all({[-1]="Hello",[0]="World"}, -1, 0)

socket:send_multipart ()

This is alias for socket:send_all

socket:sendx (...)

Send a multipart message over Socket.

Parameters:

• ... string parts of message.

Returns:

true

Or

1. nil
2. error
3. number index of error part

Usage:

skt:sendx("Hello","World")

socket:sendx_more (...)

Send a multipart message over Socket. This function always set flag zmq.SNDMORE to message

Parameters:

• ... string parts of message.

Returns:

true

Or

1. nil
2. error
3. number index of error part

socket:sendv (...)

Send a message over Socket. This function concatinate all parts and send result string.

Parameters:

• ... string parts of message.

Returns:

true

Or

1. nil
2. error
3. number index of error part

Usage:

skt:sendv("Hello","World")

socket:sendv_more (...)

Send a message over Socket. This function concatinate all parts and send result string. This function always set flag zmq.SNDMORE to message.

Parameters:

• ... string parts of message.

Returns:

true

Or

1. nil
2. error
3. number index of error part

socket:recv ([flags=0])

Receive a message.

Parameters:

• flags number zmq receive flags. (default 0)

Returns:

1. string message
2. bool more flag

Or

1. nil
2. error

Usage:

 more = true
 while more do
   msg, more = skt:recv()
   ...
 emd

socket:recv_len (len[, flags=0])

Receive first bytes from message.

Parameters:

• len number number of bytes to receive
• flags number zmq receive flags. (default 0)

Returns:

1. first bytes from message
2. bool more flag
3. number full size of message

Or

1. nil
2. error

socket:recv_msg (number[, flags=0])

Receive a message.

Parameters:

• number message flags zmq receive flags.
• flags number zmq receive flags. (default 0)

Returns:

1. message message
2. bool more flag

Or

1. nil
2. error

socket:recv_new_msg ([flags=0])

Receive a message. This function create new `message` object.

Parameters:

• flags number zmq receive flags. (default 0)

Returns:

1. message message
2. bool more flag

Or

1. nil
2. error

socket:recv_all ([flags=0])

Receive multipart message.

Parameters:

• flags number zmq receive flags. (default 0)

Returns:

table array of parts of message

Or

1. nil
2. error
3. table received part of message

socket:recv_multipart ()

This is alias for `socket:recv_all`

socket:recvx ([flags=0])

Receive multipart message.

Parameters:

• flags number zmq receive flags. (default 0)

Returns:

... parts of message

Or

1. nil
2. error
3. ... received parts of message

socket:recv_event ([flags=0])

Receive zmq event message.

Parameters:

• flags number zmq receive flags. (default 0)

Returns:

1. number envet
2. number value
3. string address

Or

1. nil
2. error

socket:monitor ([address[, enents=zmq.EVENT_ALL]])

Start publishing socket events on inproc. This function generate unique address if it not provided. Also you could provide only event bitmask.

Parameters:

• address string address used for monitoring
• enents number zmq envent bitmask (default zmq.EVENT_ALL)

Returns:

string address used for monitoring

Or

1. nil
2. error

See also:

socket:reset_monitor

Usage:

 -- create monitor socket
 local mon = ctx:socket{zmq.PAIR, connect = skt:monitor()}

socket:reset_monitor ()

Stop publishing socket events.

Returns:

boolean

Or

1. nil
2. error

See also:

socket:monitor

socket:has_event (mask)

Check if socket has specific event state.

Parameters:

• mask number event mask (zmq.POLLIN, zmq.POLLOUT)

Returns:

boolean

Or

1. nil
2. error

Usage:

 -- Polling zmq socket using libuv (use lua-lluv binding)

 -- start polling zmq socket (e.g. ZMQ_SUB)
 uv.poll_socket(sock:fd()):start(function(handle, err)
   -- We need read all messages from zmq socket
   while sock:has_event(zmq.POLLIN) do
     local msg, err = sock:recv() -- we have no need use zmq.DONTWAIT
     ...
   end
 end)

Class message

This is wrapper around zmq_msg_t. But `message` object could reallocate and copy data to new zmq_msg_t object if needed. So you always could use same object while you do not call close method.

message:close ()

Close message.

Returns:

bool true - you can no longer use this Message

message:closed ()

Check if this Message has been closed.

Returns:

bool true - you can no longer use this Message

message:move ()

Move current message to new one. Afetr that function current message has no data.

Returns:

message new created message.

Or

1. nil
2. error

Usage:

 local new_msg = msg:move()
 assert (msg:data() == "")

message:move (source)

Move source message to current one. After a call of this function the source message has no data.

Parameters:

• source message

Returns:

message current message.

Or

1. nil
2. error

Usage:

 new_msg = zmq.msg_init():move(msg)
 assert (msg:data() == "")

message:copy ()

Copy current message to new one.

Returns:

message new created message.

Or

1. nil
2. error

message:copy (source)

Copy source message to current one.

Parameters:

• source message

Returns:

message current message.

Or

1. nil
2. error

message:size ()

Get size of message in bytes.

Returns:

number size in bytes.

message:set_size (size)

Set size of message in bytes. This function create new zmq_msg_t and copy data from current message.

Parameters:

• size number

Returns:

bool true

message:pointer ()

Get internal pointer to zmq_msg_t data. This pounter can be invalidate with some functions (e.g. message:set_size()).

Returns:

lightuserdata

message:data ()

Get data of message as string.

Returns:

string

message:set_data ([position=1], data)

Set data of message. This function can resize message if it is necessary.

Parameters:

• position number start position to data (default 1)
• data string

Returns:

true

Usage:

 msg:set_data("Hello")
 msg:set_data(6, ", world!")

message:more ()

Check if this message is not last in multipart message.

Returns:

bool

message:get (property)

Get ZMQ message property.

Parameters:

• property number

Returns:

number property value

Or

1. nil
2. error

message:set (property, value)

Set ZMQ message property.

Parameters:

• property number
• value number

Returns:

bool true

Or

1. nil
2. error

message:send (socket[, flags=0])

Send message.

Parameters:

• socket socket
• flags number (default 0)

Returns:

bool true

Or

1. nil
2. error

message:send_more (socket[, flags=zmq.SNDMORE])

Send message. This function always set zmq.SNDMORE flag.

Parameters:

• socket socket
• flags number (default zmq.SNDMORE)

Returns:

bool true

Or

1. nil
2. error

message:recv (socket)

Receive message.

Parameters:

• socket socket

Returns:

bool true

Or

1. nil
2. error