SYNOPSIS

int zmq_device (int device, const void *frontend, const void *backend);

DESCRIPTION

The zmq_device() function starts a built-in ØMQ device. The device argument is one of:

ZMQ_QUEUE

starts a queue device

ZMQ_FORWARDER

starts a forwarder device

ZMQ_STREAMER

starts a streamer device

The device connects a frontend socket to a backend socket. Conceptually, data flows from frontend to backend. Depending on the socket types, replies may flow in the opposite direction.

Before calling zmq_device() you must set any socket options, and connect or bind both frontend and backend sockets. The two conventional device models are:

  • proxy model - accept inward connections to frontend socket (by binding it to an endpoint), and make onward connections through backend socket (connecting to endpoints on other nodes). A proxy device model can fit well into an existing topology.

  • broker model - accept connections on both frontend and backend sockets (by binding both to endpoints). A broker device model creates a star topology where nodes can come and go at any time.

zmq_device() runs in the current thread and returns only if/when the current context is closed.

QUEUE DEVICE

ZMQ_QUEUE creates a shared queue that collects requests from a set of clients, and distributes these fairly among a set of services. Requests are fair-queued from frontend connections and load-balanced between backend connections. Replies automatically return to the client that made the original request.

This device is part of the request-reply pattern. The frontend speaks to clients and the backend speaks to services. You should use ZMQ_QUEUE with a ZMQ_XREP socket for the frontend and a ZMQ_XREQ socket for the backend. Other combinations are not documented.

Refer to zmq_socket(3) for a description of these socket types.

FORWARDER DEVICE

ZMQ_FORWARDER collects messages from a set of publishers and forwards these to a set of subscribers. You will generally use this to bridge networks, e.g. read on TCP unicast and forward on multicast.

This device is part of the publish-subscribe pattern. The frontend speaks to publishers and the backend speaks to subscribers. You should use ZMQ_FORWARDER with a ZMQ_SUB socket for the frontend and a ZMQ_PUB socket for the backend. Other combinations are not documented.

Refer to zmq_socket(3) for a description of these socket types.

STREAMER DEVICE

ZMQ_STREAMER collects tasks from a set of pushers and forwards these to a set of pullers. You will generally use this to bridge networks. Messages are fair-queued from pushers and load-balanced to pullers.

This device is part of the pipeline pattern. The frontend speaks to pushers and the backend speaks to pullers. You should use ZMQ_STREAMER with a ZMQ_PULL socket for the frontend and a ZMQ_PUSH socket for the backend. Other combinations are not documented.

Refer to zmq_socket(3) for a description of these socket types.

RETURN VALUE

The zmq_device() function shall not return if successful. Otherwise it shall return -1 and set errno to one of the values defined below.

ERRORS

ETERM

The ØMQ context associated with the specified frontend or backend was terminated.

EFAULT

The provided frontend or backend was not valid (NULL).

EXAMPLE

Creating a queue broker
//  Create frontend and backend sockets
void *frontend = zmq_socket (context, ZMQ_XREP);
assert (backend);
void *backend = zmq_socket (context, ZMQ_XREQ);
assert (frontend);
//  Bind both sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
//  Start a queue device
zmq_device (ZMQ_QUEUE, frontend, backend);
Creating a pubsub proxy
//  Create frontend and backend sockets
void *frontend = zmq_socket (context, ZMQ_SUB);
assert (backend);
void *backend = zmq_socket (context, ZMQ_PUB);
assert (frontend);
//  Connect frontend to publisher
assert (zmq_bind (frontend, "tcp://192.68.55.112:4444") == 0);
//  Bind backend to TCP port
assert (zmq_bind (backend, "tcp://*:5556") == 0);
//  Start a forwarder device
zmq_device (ZMQ_FORWARDER, frontend, backend);

SEE ALSO