ZeroMQ Quick Reference

Install, Include, Link

Install

On archlinux:

sudo pacman -Sy zeromq

Include

To use zmq you need to include the zmq.h C header.

#include <zmq.h>

int main(void)
{
    /* ... */

    return (0);
}

Link

To compile a binary you need to link libzmq.

gcc prog.o -lzmq -o prog

If you using make you can (probably) just add

prog: -lzmq

at the end of your Makefile.

ZMQ Context

Construct / Deconstruct

Created with

void    *zmq_ctx_new(void);

Destroyed with

int zmq_ctx_shutdown(void *ctx);
int zmq_ctx_term(void *ctx);

Context attributes

Youy can get/set context attributes with

int zmq_ctx_set(void *ctx, int attr, int val);
int zmq_ctx_get(void *ctx, int attr);

The full list of ZeroMQ context attributes can be found here

ZMQ Socket

Construct / Deconstruct

All zmq_sockets are created with

int zmq_socket(void *ctx, int type);

Valid socet types are: ZMQ_CLIENT, ZMQ_SERVER, ZMQ_DISH, ZMQ_RADIO, ZMQ_SUB, ZMQ_XSUB, ZMQ_PUB, ZMQ_XPUB, ZMQ_PULL, ZMQ_PUSH, ZMQ_SCATTER, ZMQ_GATHER, ZMQ_PAIR, ZMQ_PEER, ZMQ_CHANNEL, ZMQ_STREAM, ZMQ_REQ, ZMQ_REP, ZMQ_DEALER, ZMQ_ROUTER. Check here for a description of these socket patterns.

Once the socket has finished its job, the socket should be closed.

int zmq_close(void *socket);

Bind / Connect ZMQ sockets

A server is a zmq_socket that binds to an endpoint.

A client is a zmq_socket that connects to an endpoint.

In zmq an endpoint is a string of the form:

ENDPOINT=${TRANSPORT}://${ADDRESS}

At the moment ZMQ supports the following transports: tcp, ipc, inproc, pgm, epgm, vmci, udp.

There is no zmq_accept: if a socket is bound to an endpoint it automatically accepts connections.

Socket Attributes

You can get/set zmq_socket attributes with

zmq_getsockopt(void *socket, int attr);
zmq_setsockopt(void *socket, int attr, int val);

For a full list of socket attributes, see here

ZMQ Messages

Construct / Deconstruct

int zmq_msg_init(zmq_msg_t *msg);   /* msg is not an empty message */
int zmq_msg_close(zmq_msg_t *msg);  /* frees the message */

Messages can be initialized also with

int zmq_msg_init_size(zmq_msg_t *msg, size_t size);
int zmq_msg_init_buffer (zmq_msg_t *msg, const void *buf, size_t size);
int zmq_msg_init_data(zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *del, void *hint);

where

typedef void (zmq_free_fn) (void *data, void *hint);

You have to use exactly one message initializer, if you use more it may lead to undefined behavior.

Getters

int         zmq_msg_more(zmq_msg_t *msg);
void        zmq_msg_data(zmq_msg_t *msg);
size_t      zmq_msg_size(zmq_msg_t *msg);

uint32_t    zmq_msg_routing_id(zmq_msg_t *msg);

Copy / Move

int zmq_msg_move(zmq_msg_t *dst, zmq_msg_t *src);
int zmq_msg_copy(zmq_msg_t *dst, zmq_msg_t *src);

Send / Receive Messages

int zmq_msg_send(zmq_msg_t  *msg, void *socket, int flags);
int zmq_msg_recv(zmq_msg_t  *msg, void *socket, int flags);

Flags:

• ZMQ_DONTWAIT,
• ZMQ_SNDMORE (only for zmq_msg_send),

Message Attributes

int zmq_msg_get(zmq_msg_t *msg, int attr);
int zmq_msg_set(zmq_msg_t *msg, int attr, int val);

ZMQ_MORE ZMQ_SRCFD ZMQ_SHARED

ZMQ Poller

Construct / Deconstruct

void    *zmq_poller_new (void);
int     zmq_poller_destroy (void **poller_p);

Getters

int zmq_poller_fd (void *poller, zmq_fd_t *fd);
int zmq_poller_size (void *poller);

Socket API

int zmq_poller_add (void *poller, void *socket, void *user_data, short events);
int zmq_poller_modify (void *poller, void *socket, short events);
int zmq_poller_remove (void *poller, void *socket);

FD API

int zmq_poller_add_fd (void *poller, int fd, void *user_data, short events);
int zmq_poller_modify_fd (void *poller, int fd, short events);
int zmq_poller_remove_fd (void *poller, int fd);

Wait for events

int zmq_poller_wait (void *poller, zmq_poller_event_t *event, long timeout);
int zmq_poller_wait_all (void *poller, zmq_poller_event_t *events, int n_events, long timeout);

Events

typedef struct
{
    void        *socket;
    zmq_fd_t    fd;
    void        *user_data;
    short       events;
} zmq_poller_event_t;

The events field

• ZMQ_POLLIN
• ZMQ_POLLOUT
• ZMQ_POLLERR
• ZMQ_POLLPRI

ZMQ Proxy

Proxies are used to connect two exixsting and pre-connected sockets.

int zmq_proxy(void *frontend, void *backend, void *capture);
int zmq_proxy_steerable(void *frontend, void *backend, void *capture, void *control);

For both functions, all parameters are zmq_sockets.

While a proxy is bidirectional, it usefule to think that data flows from frontend to backend.

The control socket is used to send commands to the proxy. The control socket is of type ZMQ_REP. Valid commands are: PAUSE, RESUME, TERMINATE, STATISTICS. If control is NULL, zmq_proxy_steerable behaves exactly as zmq_proxy.

The capture socket sends all data received by the frontend and backend socket. The capture socket type (if the socket is not NULL) has to be one of the following: ZMQ_PUB, ZMQ_DEALER, ZMQ_PUSH, ZMQ_PAIR.