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. Each ØMQ socket belonging to a particular context may only be used -by the thread that created it using zmq_socket().

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

Apart from the ØMQ library the ØMQ distribution includes devices which are -building blocks intended to serve as intermediate nodes in complex messaging -topologies.

The following devices are provided:

-Forwarder device for request-response messaging -: -
- zmq_queue(1) -
-
-Forwarder device for publish-subscribe messaging -: -
- zmq_forwarder(1) -
-
-Streamer device for parallelized pipeline messaging -: -
- zmq_streamer(1) -
-

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

The ØMQ documentation 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