Qore zmq Module

Table of Contents

• zmq Module Introduction
• Examples
• zmq Endpoints
  • Binding TCP Endpoints
• zmq Errors
• zmq Encryption
• zmq Module Release Notes
  • zmq Module Version 1.0

zmq Module Introduction

The zmq module provides an API for socket operations based on the ZeroMQ library.

Classes provided by this module:

• ZFrame
• ZMsg
• ZSocket
  • ZSocketDealer
  • ZSocketPair
  • ZSocketPub
  • ZSocketPull
  • ZSocketPush
  • ZSocketRep
  • ZSocketReq
  • ZSocketRouter
  • ZSocketStream
  • ZSocketSub
  • ZSocketXPub
  • ZSocketXSub

Functions provided by this module:

• zmq_curve_keypair()
• zmq_curve_public()
• zmq_version()
• zmq_z85_encode()

Unlike the ZeroMQ C library which uses an unlimited timeout period on socket send and receive operations by default, the socket timeout in the Qore ZSocket class is set by default to two minutes; to change the default timeout, call one of the following methods after creating the object:

• ZSocket::setRecvTimeout()
• ZSocket::setSendTimeout()
• ZSocket::setTimeout()

Timeout Example:

# create a ROUTER socket on all devices on a wildcard/random port
ZSocketRouter sock(zctx, name, "tcp://*:*");
# set the default send and receive timeout to unlimited (never time out)
sock.setTimeout(-1);
# print out the URL with the actual port number
printf("queue URL bound to: %y\n", sock.endpoint());

Examples

Example:

#!/usr/bin/env qore

%new-style
%require-types
%strict-args
%enable-all-warnings

%requires zmq

zmq Endpoints

Endpoints have the following format:

• [@|>]transport://address

Endpoint prefixes have the following meaning:

• @: bind the socket
• >: connect to the remote socket

Example transports:

• tcp://: for TCP socket connections
• inproc://: for in-process connections

Binding TCP Endpoints

tcp:// endpoints support binding on a random free port if you specify the port number as "*", "!", or 0 and support binding on all interfaces if you specify the interface or host name as "*".

Examples

Endpoint	Description
@tcp://127.0.0.1:0	bind to random port on localhost
@tcp://127.0.0.1:*	bind to random port on localhost
@tcp://127.0.0.1:!	bind to random port on localhost
@tcp://*:0	bind to random port on all interfaces
@tcp://*:*	bind to random port on all interfaces
@tcp://*:!	bind to random port on all interfaces

zmq Errors

Generally exceptions are thrown if an error occurs in ZeroMQ calls. In such cases, the arg key of the exception hash will contain the ZeroMQ errno value.

zmq Encryption

Encryption is supported using the Curve implementation in ZeroMQ.

Encryption keys must be either 32-byte binary values or 40-byte Z85 formatted printable strings. Z85 formatted printable strings can be generated with the zmq_z85_encode().

A public key must be generated from the private key; this can be done with either the zmq_curve_keypair() function, which generates a random private key and a matching public key, or with the zmq_curve_public() function.

Encryption options are set with the ZSocket::setOption() method; see the following example for information on how to set the encryption settings on the client and the server.

Example:

# generate a printable random server key
string server_secret = zmq_z85_encode(get_random_bytes(32));
# generate the corresponding public key
string server_pub = zmq_curve_public(server_secret);
# generate a printable random client key
string client_secret = zmq_z85_encode(get_random_bytes(32));
# generate the corresponding public key
string client_pub = zmq_curve_public(client_secret);

# create the server socket
ZSocketRouter server(zctx, "my-server");
# set encryption options; ZMQ_CURVE_SERVER must only be set on the server
server.setOption(ZMQ_CURVE_SERVER, 1);
server.setOption(ZMQ_CURVE_SECRETKEY, server_secret);
server.setOption(ZMQ_CURVE_PUBLICKEY, server_pub);
# bind the server on a random port
server.bind("tcp://127.0.0.1:*");

# create the client socket
ZSocketDealer client(zctx, "my-client");
# set encryption options; ZMQ_CURVE_SERVER must only be set on the server
client.setOption(ZMQ_CURVE_SERVER, 0);
client.setOption(ZMQ_CURVE_SERVERKEY, server_pub);
client.setOption(ZMQ_CURVE_SECRETKEY, client_secret);
client.setOption(ZMQ_CURVE_PUBLICKEY, client_pub);

# connect to the server
client.connect(server.endpoint());

# now we can send data
client.send(HelloWorld);
ZMsg msg = server.recvMsg();

zmq Module Release Notes

zmq Module Version 1.0

• initial public release