mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-26 23:01:04 +08:00
b6ca9b2983
* migrate from the old, unmaintained "asciidoc-py" tool to the new "asciidoctor" generator * migrate from asciidoc-py syntax to the modern Asciidoc syntax (especially page titles and section titles) * remove the need of "xmlto" utility to create the manpage output; use asciidoctor for that * add HTML output support to the doc/Makefile by using asciidoctor * change API documentation files extension from .txt to .adoc to make it more explicit that they are Asciidoc-encoded (as a bonus several IDE plugins will autodetect the .adoc format as Asciidoc) * remove asciidoc.conf: asciidoctor does not support that; this also required replacing the macro linkzmq into all documentation pages * add a new Github action CI do deploy to Github Pages the static HTMLs produced by Asciidoctors * removed references to the "xmlto" and "a2x" tools from the build and packaging systems: Asciidoctor can convert the documentation directly to e.g. pdf (via extended converters) and anyway there was no code/target for using "xmlto" and "a2x" tools anyway
270 lines
8.6 KiB
Plaintext
270 lines
8.6 KiB
Plaintext
= zmq(7)
|
|
|
|
|
|
== NAME
|
|
zmq - 0MQ lightweight messaging kernel
|
|
|
|
|
|
== SYNOPSIS
|
|
*#include <zmq.h>*
|
|
|
|
*cc* ['flags'] 'files' *-lzmq* ['libraries']
|
|
|
|
|
|
== DESCRIPTION
|
|
The 0MQ lightweight messaging kernel is a library which extends the standard
|
|
socket interfaces with features traditionally provided by specialised
|
|
_messaging middleware_ products. 0MQ 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 0MQ concepts, describes how 0MQ
|
|
abstracts standard sockets and provides a reference manual for the functions
|
|
provided by the 0MQ library.
|
|
|
|
|
|
Context
|
|
~~~~~~~
|
|
The 0MQ 'context' keeps the list of sockets and manages the async I/O thread
|
|
and internal queries.
|
|
|
|
Before using any 0MQ library functions you must create a 0MQ 'context'. When
|
|
you exit your application you must destroy the 'context'. These functions let
|
|
you work with 'contexts':
|
|
|
|
Create a new 0MQ context::
|
|
* xref:zmq_ctx_new.adoc[zmq_ctx_new]
|
|
|
|
Work with context properties::
|
|
* xref:zmq_ctx_set.adoc[zmq_ctx_set]
|
|
* xref:zmq_ctx_get.adoc[zmq_ctx_get]
|
|
|
|
Destroy a 0MQ context::
|
|
* xref:zmq_ctx_shutdown.adoc[zmq_ctx_shutdown]
|
|
* xref:zmq_ctx_term.adoc[zmq_ctx_term]
|
|
|
|
Thread safety
|
|
^^^^^^^^^^^^^
|
|
A 0MQ '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 0MQ '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
|
|
initialisation, 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 0MQ directly and at the same time make use of any number of
|
|
additional libraries or components which themselves make use of 0MQ as long as
|
|
the above guidelines regarding thread safety are adhered to.
|
|
|
|
|
|
Messages
|
|
~~~~~~~~
|
|
A 0MQ message is a discrete unit of data passed between applications or
|
|
components of the same application. 0MQ messages have no internal structure and
|
|
from the point of view of 0MQ itself they are considered to be opaque binary
|
|
data.
|
|
|
|
The following functions are provided to work with messages:
|
|
|
|
Initialise a message::
|
|
* xref:zmq_msg_init.adoc[zmq_msg_init]
|
|
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
|
|
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
|
|
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
|
|
|
|
Sending and receiving a message::
|
|
* xref:zmq_msg_send.adoc[zmq_msg_send]
|
|
* xref:zmq_msg_recv.adoc[zmq_msg_recv]
|
|
|
|
Release a message::
|
|
* xref:zmq_msg_close.adoc[zmq_msg_close]
|
|
|
|
Access message content::
|
|
* xref:zmq_msg_data.adoc[zmq_msg_data]
|
|
* xref:zmq_msg_size.adoc[zmq_msg_size]
|
|
* xref:zmq_msg_more.adoc[zmq_msg_more]
|
|
|
|
Work with message properties::
|
|
* xref:zmq_msg_gets.adoc[zmq_msg_gets]
|
|
* xref:zmq_msg_get.adoc[zmq_msg_get]
|
|
* xref:zmq_msg_set.adoc[zmq_msg_set]
|
|
|
|
Message manipulation::
|
|
* xref:zmq_msg_copy.adoc[zmq_msg_copy]
|
|
* xref:zmq_msg_move.adoc[zmq_msg_move]
|
|
|
|
|
|
Sockets
|
|
~~~~~~~
|
|
0MQ sockets present an abstraction of an asynchronous _message queue_, with the
|
|
exact queueing semantics depending on the socket type in use. See
|
|
xref:zmq_socket.adoc[zmq_socket] for the socket types provided.
|
|
|
|
The following functions are provided to work with sockets:
|
|
|
|
Creating a socket::
|
|
* xref:zmq_socket.adoc[zmq_socket]
|
|
|
|
Closing a socket::
|
|
* xref:zmq_close.adoc[zmq_close]
|
|
|
|
Manipulating socket options::
|
|
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
|
|
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
|
|
|
|
Establishing a message flow::
|
|
* xref:zmq_bind.adoc[zmq_bind]
|
|
* xref:zmq_connect.adoc[zmq_connect]
|
|
|
|
Sending and receiving messages::
|
|
* xref:zmq_msg_send.adoc[zmq_msg_send]
|
|
* xref:zmq_msg_recv.adoc[zmq_msg_recv]
|
|
* xref:zmq_send.adoc[zmq_send]
|
|
* xref:zmq_recv.adoc[zmq_recv]
|
|
* xref:zmq_send_const.adoc[zmq_send_const]
|
|
|
|
Monitoring socket events::
|
|
* xref:zmq_socket_monitor.adoc[zmq_socket_monitor]
|
|
|
|
.Input/output multiplexing
|
|
0MQ provides a mechanism for applications to multiplex input/output events over
|
|
a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
|
|
the standard _poll()_ system call, and is described in detail in
|
|
xref:zmq_poll.adoc[zmq_poll] This API is deprecated, however.
|
|
|
|
There is a new DRAFT API with multiple zmq_poller_* function, which is described
|
|
in xref:zmq_poller.adoc[zmq_poller]
|
|
|
|
|
|
Transports
|
|
~~~~~~~~~~
|
|
A 0MQ 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::
|
|
* xref:zmq_tcp.adoc[zmq_tcp]
|
|
|
|
Reliable multicast transport using PGM::
|
|
* xref:zmq_pgm.adoc[zmq_pgm]
|
|
|
|
Local inter-process communication transport::
|
|
* xref:zmq_ipc.adoc[zmq_ipc]
|
|
|
|
Local in-process (inter-thread) communication transport::
|
|
* xref:zmq_inproc.adoc[zmq_inproc]
|
|
|
|
Virtual Machine Communications Interface (VMC) transport::
|
|
* xref:zmq_vmci.adoc[zmq_vmci]
|
|
|
|
Unreliable unicast and multicast using UDP::
|
|
* xref:zmq_udp.adoc[zmq_udp]
|
|
|
|
|
|
Proxies
|
|
~~~~~~~
|
|
0MQ provides 'proxies' to create fanout and fan-in topologies. A proxy connects
|
|
a 'frontend' socket to a 'backend' socket and switches all messages between the
|
|
two sockets, opaquely. A proxy may optionally capture all traffic to a third
|
|
socket. To start a proxy in an application thread, use xref:zmq_proxy.adoc[zmq_proxy]
|
|
|
|
|
|
Security
|
|
~~~~~~~~
|
|
A 0MQ socket can select a security mechanism. Both peers must use the same
|
|
security mechanism.
|
|
|
|
The following security mechanisms are provided for IPC and TCP connections:
|
|
|
|
Null security::
|
|
* xref:zmq_null.adoc[zmq_null]
|
|
|
|
Plain-text authentication using username and password::
|
|
* xref:zmq_plain.adoc[zmq_plain]
|
|
|
|
Elliptic curve authentication and encryption::
|
|
* xref:zmq_curve.adoc[zmq_curve]
|
|
|
|
Generate a CURVE keypair in armored text format::
|
|
* xref:zmq_curve_keypair.adoc[zmq_curve_keypair]
|
|
|
|
Derive a CURVE public key from a secret key::
|
|
* xref:zmq_curve_public.adoc[zmq_curve_public]
|
|
|
|
Converting keys to/from armoured text strings::
|
|
* xref:zmq_z85_decode.adoc[zmq_z85_decode]
|
|
* xref:zmq_z85_encode.adoc[zmq_z85_encode]
|
|
|
|
|
|
== ERROR HANDLING
|
|
The 0MQ library functions handle errors using the standard conventions found on
|
|
POSIX systems. Generally, this means that upon failure a 0MQ 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 xref:zmq_errno.adoc[zmq_errno]
|
|
|
|
The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
|
|
into error message strings; for details refer to xref:zmq_strerror.adoc[zmq_strerror]
|
|
|
|
|
|
== UTILITY
|
|
The following utility functions are provided:
|
|
|
|
Working with atomic counters::
|
|
* xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new]
|
|
* xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set]
|
|
* xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc]
|
|
* xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec]
|
|
* xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value]
|
|
* xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy]
|
|
|
|
|
|
== MISCELLANEOUS
|
|
The following miscellaneous functions are provided:
|
|
|
|
Report 0MQ library version::
|
|
* xref:zmq_version.adoc[zmq_version]
|
|
|
|
|
|
== LANGUAGE BINDINGS
|
|
The 0MQ 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 0MQ from other languages
|
|
shall refer to this documentation alongside any documentation provided by the
|
|
vendor of their language binding.
|
|
|
|
Language bindings ($$C++$$, Python, PHP, Ruby, Java and more) are provided by
|
|
members of the 0MQ community and pointers can be found on the 0MQ website.
|
|
|
|
|
|
== AUTHORS
|
|
This page was written by the 0MQ community. To make a change please
|
|
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.
|
|
|
|
|
|
== RESOURCES
|
|
Main web site: <http://www.zeromq.org/>
|
|
|
|
Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
|
|
|
|
|
|
== LICENSE
|
|
Free use of this software is granted under the terms of the Mozilla Public
|
|
License Version 2.0 (MPL-2.0). For details see the file `LICENSE` included with
|
|
the 0MQ distribution.
|