zmq(7)

SYNOPSIS

#include <zmq.h>

cc [flags] files -lzmq [libraries]

DESCRIPTION

The ØMQ lightweight messaging kernel is a library which extends the standard +socket interfaces with features traditionally provided by specialised +messaging middleware products. ØMQ sockets provide an abstraction of +asynchronous message queues, multiple messaging patterns, message +filtering (subscriptions), seamless access to multiple transport protocols +and more.

This documentation presents an overview of ØMQ concepts, describes how ØMQ +abstracts standard sockets and provides a reference manual for the functions +provided by the ØMQ library.

Context

Before using any ØMQ library functions the caller must initialise a ØMQ +context using zmq_init(). The following functions are provided to handle +initialisation and termination of a context:

+Initialise ØMQ context +: +
+ zmq_init(3) +
+
+Terminate ØMQ context +: +
+ zmq_term(3) +
+

Thread safety

A ØMQ context is thread safe and may be shared among as many application +threads as necessary, without any additional locking required on the part of +the caller.

Individual ØMQ sockets are not thread safe except in the case where full +memory barriers are issued when migrating a socket from one thread to another. +In practice this means applications can create a socket in one thread with +zmq_socket() and then pass it to a newly created thread as part of thread +initialization, for example via a structure passed as an argument to +pthread_create().

Multiple contexts

Multiple contexts may coexist within a single application. Thus, an +application can use ØMQ directly and at the same time make use of any number of +additional libraries or components which themselves make use of ØMQ as long as +the above guidelines regarding thread safety are adhered to.

Messages

A ØMQ message is a discrete unit of data passed between applications or +components of the same application. ØMQ messages have no internal structure and +from the point of view of ØMQ itself they are considered to be opaque binary +data.

The following functions are provided to work with messages:

+Initialise a message +: +
+ zmq_msg_init(3) + zmq_msg_init_size(3) + zmq_msg_init_data(3) +
+
+Release a message +: +
+ zmq_msg_close(3) +
+
+Access message content +: +
+ zmq_msg_data(3) + zmq_msg_size(3) +
+
+Message manipulation +: +
+ zmq_msg_copy(3) + zmq_msg_move(3) +
+

Sockets

ØMQ sockets present an abstraction of a asynchronous message queue, with the +exact queueing semantics depending on the socket type in use. See +zmq_socket(3) for the socket types provided.

The following functions are provided to work with sockets:

+Creating a socket +: +
+ zmq_socket(3) +
+
+Closing a socket +: +
+ zmq_close(3) +
+
+Manipulating socket options +: +
+ zmq_getsockopt(3) + zmq_setsockopt(3) +
+
+Establishing a message flow +: +
+ zmq_bind(3) + zmq_connect(3) +
+
+Sending and receiving messages +: +
+ zmq_send(3) + zmq_recv(3) +
+

Input/output multiplexing

ØMQ provides a mechanism for applications to multiplex input/output events over +a set containing both ØMQ sockets and standard sockets. This mechanism mirrors +the standard poll() system call, and is described in detail in +zmq_poll(3).

Transports

A ØMQ socket can use multiple different underlying transport mechanisms. +Each transport mechanism is suited to a particular purpose and has its own +advantages and drawbacks.

The following transport mechanisms are provided:

+Unicast transport using TCP +: +
+ zmq_tcp(7) +
+
+Reliable multicast transport using PGM +: +
+ zmq_pgm(7) +
+
+Local inter-process communication transport +: +
+ zmq_ipc(7) +
+
+Local in-process (inter-thread) communication transport +: +
+ zmq_inproc(7) +
+

Devices

ØMQ provides devices, which are building blocks that act as intermediate +nodes in complex messaging topologies. Devices can act as brokers that other +nodes connect to, proxies that connect through to other nodes, or any mix of +these two models.

You can start a device in an application thread, see zmq_device(3).

ERROR HANDLING

The ØMQ library functions handle errors using the standard conventions found on +POSIX systems. Generally, this means that upon failure a ØMQ library function +shall return either a NULL value (if returning a pointer) or a negative value +(if returning an integer), and the actual error code shall be stored in the +errno variable.

On non-POSIX systems some users may experience issues with retrieving the +correct value of the errno variable. The zmq_errno() function is provided +to assist in these cases; for details refer to zmq_errno(3).

The zmq_strerror() function is provided to translate ØMQ-specific error codes +into error message strings; for details refer to zmq_strerror(3).

MISCELLANEOUS

The following miscellaneous functions are provided:

+Report ØMQ library version +: +
+ zmq_version(3) +
+

LANGUAGE BINDINGS

The ØMQ library provides interfaces suitable for calling from programs in any +language; this documentation documents those interfaces as they would be used +by C programmers. The intent is that programmers using ØMQ from other languages +shall refer to this documentation alongside any documentation provided by the +vendor of their language binding.

C++ language binding

The ØMQ distribution includes a C++ language binding, which is documented +separately in zmq_cpp(7).

Other language bindings

Other language bindings (Python, Ruby, Java and more) are provided by members +of the ØMQ community and pointers can be found on the ØMQ website.

AUTHORS

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

RESOURCES

Main web site: http://www.zeromq.org/

Report bugs to the ØMQ development mailing list: <zeromq-dev@lists.zeromq.org>

COPYING

Free use of this software is granted under the terms of the GNU Lesser General +Public License (LGPL). For details see the files COPYING and COPYING.LESSER +included with the ØMQ distribution.

+zmq(7) Manual Page +

NAME