thijn/SqMod
1
0
Fork 0
mirror of https://github.com/VCMP-SqMod/SqMod.git synced 2026-01-19 21:54:40 +01:00
Code Releases Activity

Initial ZMQ bindings.

Browse Source
This commit is contained in:
Sandu Liviu Catalin
2021-02-02 19:07:02 +02:00
parent 82b7f75b80
commit fc9419677f
1092 changed files with 147348 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
vendor/ZMQ/doc/Makefile.am vendored Normal file
View File

@@ -0,0 +1,66 @@
#
# documentation
#
MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_close.3 \
zmq_ctx_new.3 zmq_ctx_term.3 zmq_ctx_get.3 zmq_ctx_set.3 zmq_ctx_shutdown.3 \
zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_init_buffer.3 \
zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \
zmq_msg_send.3 zmq_msg_recv.3 \
zmq_msg_routing_id.3 zmq_msg_set_routing_id.3 \
zmq_send.3 zmq_recv.3 zmq_send_const.3 \
zmq_msg_get.3 zmq_msg_set.3 zmq_msg_more.3 zmq_msg_gets.3 \
zmq_getsockopt.3 zmq_setsockopt.3 \
zmq_socket.3 zmq_socket_monitor.3 zmq_poll.3 \
zmq_socket_monitor_versioned.3 \
zmq_errno.3 zmq_strerror.3 zmq_version.3 \
zmq_sendmsg.3 zmq_recvmsg.3 \
zmq_proxy.3 zmq_proxy_steerable.3 \
zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3 zmq_curve_public.3 \
zmq_has.3 \
zmq_timers.3 zmq_poller.3 \
zmq_atomic_counter_new.3 zmq_atomic_counter_set.3 \
zmq_atomic_counter_inc.3 zmq_atomic_counter_dec.3 \
zmq_atomic_counter_value.3 zmq_atomic_counter_destroy.3
MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7 zmq_vmci.7 zmq_udp.7 \
zmq_gssapi.7
MAN_DOC =
MAN_TXT = $(MAN3:%.3=%.txt)
MAN_TXT += $(MAN7:%.7=%.txt)
MAN_HTML =
MAINTAINERCLEANFILES =
EXTRA_DIST = asciidoc.conf $(MAN_TXT)
if INSTALL_MAN
MAN_DOC += $(MAN1) $(MAN3) $(MAN7)
dist_man_MANS = $(MAN_DOC)
MAINTAINERCLEANFILES += $(MAN_DOC)
endif
if BUILD_DOC
MAN_HTML += $(MAN_TXT:%.txt=%.html)
EXTRA_DIST += $(MAN_HTML)
MAINTAINERCLEANFILES += $(MAN_HTML)
SUFFIXES=.html .txt .xml .3 .7
.txt.html:
asciidoc -d manpage -b xhtml11 -f $(srcdir)/asciidoc.conf \
-azmq_version=@PACKAGE_VERSION@ -o$@ $<
.txt.xml:
asciidoc -d manpage -b docbook -f $(srcdir)/asciidoc.conf \
-azmq_version=@PACKAGE_VERSION@ -o$@ $<
.xml.1:
xmlto man $<
.xml.3:
xmlto man $<
.xml.7:
xmlto man $<
endif
dist-hook : $(MAN_DOC) $(MAN_HTML)

56
vendor/ZMQ/doc/asciidoc.conf vendored Normal file
View File

@@ -0,0 +1,56 @@
[paradef-default]
literal-style=template="literalparagraph"
[macros]
(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
ifdef::backend-docbook[]
[linkzmq-inlinemacro]
{0%{target}}
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
endif::backend-docbook[]
ifdef::backend-xhtml11[]
[linkzmq-inlinemacro]
<a href="{target}.html">{target}{0?({0})}</a>
endif::backend-xhtml11[]
ifdef::doctype-manpage[]
ifdef::backend-docbook[]
[header]
template::[header-declarations]
<refentry>
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">0MQ</refmiscinfo>
<refmiscinfo class="version">{zmq_version}</refmiscinfo>
<refmiscinfo class="manual">0MQ Manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
endif::backend-docbook[]
endif::doctype-manpage[]
ifdef::backend-xhtml11[]
[footer]
</div>
{disable-javascript%<div id="footnotes"><hr /></div>}
<div id="footer">
<div id="footer-text">
ØMQ {zmq_version}<br />
Last updated {docdate} {doctime}
</div>
</div>
</body>
</html>
endif::backend-xhtml11[]
[replacements]
ifdef::backend-xhtml11[]
0MQ=ØMQ
endif::backend-xhtml11[]

280
vendor/ZMQ/doc/zmq.txt vendored Normal file
View File

@@ -0,0 +1,280 @@
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::
linkzmq:zmq_ctx_new[3]
Work with context properties::
linkzmq:zmq_ctx_set[3]
linkzmq:zmq_ctx_get[3]
Destroy a 0MQ context::
linkzmq:zmq_ctx_shutdown[3]
linkzmq:zmq_ctx_term[3]
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::
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
Sending and receiving a message::
linkzmq:zmq_msg_send[3]
linkzmq:zmq_msg_recv[3]
Release a message::
linkzmq:zmq_msg_close[3]
Access message content::
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_more[3]
Work with message properties::
linkzmq:zmq_msg_gets[3]
linkzmq:zmq_msg_get[3]
linkzmq:zmq_msg_set[3]
Message manipulation::
linkzmq:zmq_msg_copy[3]
linkzmq:zmq_msg_move[3]
Sockets
~~~~~~~
0MQ sockets present an abstraction of an asynchronous _message queue_, with the
exact queueing semantics depending on the socket type in use. See
linkzmq:zmq_socket[3] for the socket types provided.
The following functions are provided to work with sockets:
Creating a socket::
linkzmq:zmq_socket[3]
Closing a socket::
linkzmq:zmq_close[3]
Manipulating socket options::
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
Establishing a message flow::
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
Sending and receiving messages::
linkzmq:zmq_msg_send[3]
linkzmq:zmq_msg_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_send_const[3]
Monitoring socket events::
linkzmq:zmq_socket_monitor[3]
.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
linkzmq:zmq_poll[3]. This API is deprecated, however.
There is a new DRAFT API with multiple zmq_poller_* function, which is described
in linkzmq:zmq_poller[3].
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::
linkzmq:zmq_tcp[7]
Reliable multicast transport using PGM::
linkzmq:zmq_pgm[7]
Local inter-process communication transport::
linkzmq:zmq_ipc[7]
Local in-process (inter-thread) communication transport::
linkzmq:zmq_inproc[7]
Virtual Machine Communications Interface (VMC) transport::
linkzmq:zmq_vmci[7]
Unreliable unicast and multicast using UDP::
linkzmq:zmq_udp[7]
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 linkzmq:zmq_proxy[3].
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::
linkzmq:zmq_null[7]
Plain-text authentication using username and password::
linkzmq:zmq_plain[7]
Elliptic curve authentication and encryption::
linkzmq:zmq_curve[7]
Generate a CURVE keypair in armored text format::
linkzmq:zmq_curve_keypair[3]
Derive a CURVE public key from a secret key:
linkzmq:zmq_curve_public[3]
Converting keys to/from armoured text strings::
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_z85_encode[3]
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 linkzmq:zmq_errno[3].
The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
into error message strings; for details refer to linkzmq:zmq_strerror[3].
UTILITY
-------
The following utility functions are provided:
Working with atomic counters::
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]
MISCELLANEOUS
-------------
The following miscellaneous functions are provided:
Report 0MQ library version::
linkzmq:zmq_version[3]
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>
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 0MQ distribution.

62
vendor/ZMQ/doc/zmq_atomic_counter_dec.txt vendored Normal file
View File

@@ -0,0 +1,62 @@
zmq_atomic_counter_dec(3)
=========================
NAME
----
zmq_atomic_counter_dec - decrement an atomic counter
SYNOPSIS
--------
*int zmq_atomic_counter_dec (void *counter);*
DESCRIPTION
-----------
The _zmq_atomic_counter_dec_ function decrements an atomic counter in
a threadsafe fashion. This function uses platform specific atomic
operations.
RETURN VALUE
------------
The _zmq_atomic_counter_dec()_ function returns 1 if the counter is
greater than zero after decrementing, or zero if the counter reached
zero.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]
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>.

62
vendor/ZMQ/doc/zmq_atomic_counter_destroy.txt vendored Normal file
View File

@@ -0,0 +1,62 @@
zmq_atomic_counter_destroy(3)
=============================
NAME
----
zmq_atomic_counter_destroy - destroy an atomic counter
SYNOPSIS
--------
*void zmq_atomic_counter_destroy (void **counter_p);*
DESCRIPTION
-----------
The _zmq_atomic_counter_destroy_ function destroys an atomic counter and
nullifies its reference. Pass the address of an atomic counter (void **)
rather than the counter itself. You must destroy all counters that you
create, to avoid memory leakage. This function uses platform specific
atomic operations.
RETURN VALUE
------------
The _zmq_atomic_counter_destroy()_ function has no return value.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
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>.

61
vendor/ZMQ/doc/zmq_atomic_counter_inc.txt vendored Normal file
View File

@@ -0,0 +1,61 @@
zmq_atomic_counter_inc(3)
=========================
NAME
----
zmq_atomic_counter_inc - increment an atomic counter
SYNOPSIS
--------
*int zmq_atomic_counter_inc (void *counter);*
DESCRIPTION
-----------
The _zmq_atomic_counter_inc_ function increments an atomic counter in a
threadsafe fashion. This function uses platform specific atomic
operations.
RETURN VALUE
------------
The _zmq_atomic_counter_inc()_ function returns the old value of the
counter, before incrementing.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]
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>.

62
vendor/ZMQ/doc/zmq_atomic_counter_new.txt vendored Normal file
View File

@@ -0,0 +1,62 @@
zmq_atomic_counter_new(3)
=========================
NAME
----
zmq_atomic_counter_new - create a new atomic counter
SYNOPSIS
--------
*void *zmq_atomic_counter_new (void);*
DESCRIPTION
-----------
The _zmq_atomic_counter_new_ function creates a new atomic counter. You
can use this in multithreaded applications to do, for example, reference
counting of shared objects. The atomic counter is at least 32 bits large.
This function uses platform specific atomic operations.
RETURN VALUE
------------
The _zmq_atomic_counter_new()_ function returns the new atomic counter
if successful. Otherwise it returns NULL.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]
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>.

61
vendor/ZMQ/doc/zmq_atomic_counter_set.txt vendored Normal file
View File

@@ -0,0 +1,61 @@
zmq_atomic_counter_set(3)
=========================
NAME
----
zmq_atomic_counter_set - set atomic counter to new value
SYNOPSIS
--------
*void zmq_atomic_counter_set (void *counter, int value);*
DESCRIPTION
-----------
The _zmq_atomic_counter_set_ function sets the counter to a new value,
in a threadsafe fashion. The largest value that is guaranteed to work
across all platforms is 2^31-1. This function uses platform specific
atomic operations.
RETURN VALUE
------------
The _zmq_atomic_counter_set()_ function has no return value.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]
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>.

62
vendor/ZMQ/doc/zmq_atomic_counter_value.txt vendored Normal file
View File

@@ -0,0 +1,62 @@
zmq_atomic_counter_value(3)
===========================
NAME
----
zmq_atomic_counter_value - return value of atomic counter
SYNOPSIS
--------
*int zmq_atomic_counter_value (void *counter);*
DESCRIPTION
-----------
The _zmq_atomic_counter_value_ function returns the value of an atomic
counter created by _zmq_atomic_counter_new()_. This function uses platform
specific atomic operations.
RETURN VALUE
------------
The _zmq_atomic_counter_value()_ function returns the value of the
atomic counter. If _counter_ does not point to an atomic counter created by
_zmq_atomic_counter_new()_, the behaviour is undefined.
EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----
SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_destroy[3]
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>.

105
vendor/ZMQ/doc/zmq_bind.txt vendored Normal file
View File

@@ -0,0 +1,105 @@
zmq_bind(3)
===========
NAME
----
zmq_bind - accept incoming connections on a socket
SYNOPSIS
--------
*int zmq_bind (void '*socket', const char '*endpoint');*
DESCRIPTION
-----------
The _zmq_bind()_ function binds the 'socket' to a local 'endpoint' and then
accepts incoming connections on that endpoint.
The 'endpoint' is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to bind to.
0MQ provides the the following transports:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7]
'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7]
Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' supports one-to-many and many-to-one
semantics. The precise semantics depend on the socket type and are defined in
linkzmq:zmq_socket[3].
The 'ipc', 'tcp', 'vmci' and 'udp' transports accept wildcard addresses: see
linkzmq:zmq_ipc[7], linkzmq:zmq_tcp[7], linkzmq:zmq_vmci[7] and
linkzmq:zmq_udp[7] for details.
NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_
especially for the 'tcp', 'pgm' and 'epgm' transports.
NOTE: following a _zmq_bind()_, the socket enters a 'mute' state unless or
until at least one incoming or outgoing connection is made, at which point
the socket enters a 'ready' state. In the mute state, the socket blocks or
drops messages according to the socket type, as defined in linkzmq:zmq_socket[3].
By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state.
RETURN VALUE
------------
The _zmq_bind()_ function returns zero if successful. Otherwise it returns
`-1` and sets 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*EADDRINUSE*::
The requested 'address' is already in use.
*EADDRNOTAVAIL*::
The requested 'address' was not local.
*ENODEV*::
The requested 'address' specifies a nonexistent interface.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.
EXAMPLE
-------
.Binding a publisher socket to an in-process and a TCP transport
----
/* Create a ZMQ_PUB socket */
void *socket = zmq_socket (context, ZMQ_PUB);
assert (socket);
/* Bind it to a in-process transport with the address 'my_publisher' */
int rc = zmq_bind (socket, "inproc://my_publisher");
assert (rc == 0);
/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
rc = zmq_bind (socket, "tcp://eth0:5555");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

59
vendor/ZMQ/doc/zmq_close.txt vendored Normal file
View File

@@ -0,0 +1,59 @@
zmq_close(3)
============
NAME
----
zmq_close - close 0MQ socket
SYNOPSIS
--------
*int zmq_close (void '*socket');*
DESCRIPTION
-----------
The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
argument. Any outstanding messages physically received from the network but not
yet received by the application with _zmq_recv()_ shall be discarded. The
behaviour for discarding messages sent by the application with _zmq_send()_ but
not yet physically transferred to the network depends on the value of the
_ZMQ_LINGER_ socket option for the specified 'socket'.
_zmq_close()_ must be called exactly once for each socket. If it is never called,
_zmq_ctx_term()_ will block forever. If it is called multiple times for the same
socket or if 'socket' does not point to a socket, the behaviour is undefined.
NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
this behaviour may cause the application to block when calling _zmq_ctx_term()_.
For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3].
NOTE: This API will complete asynchronously, so not everything will be deallocated
after it returns. See above for details about linger.
RETURN VALUE
------------
The _zmq_close()_ function shall return zero if successful. Otherwise it shall
return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOTSOCK*::
The provided 'socket' was NULL.
SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_ctx_term[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq[7]
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>.

109
vendor/ZMQ/doc/zmq_connect.txt vendored Normal file
View File

@@ -0,0 +1,109 @@
zmq_connect(3)
==============
NAME
----
zmq_connect - create outgoing connection from socket
SYNOPSIS
--------
*int zmq_connect (void '*socket', const char '*endpoint');*
DESCRIPTION
-----------
The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then
accepts incoming connections on that endpoint.
The 'endpoint' is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
0MQ provides the the following transports:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7]
'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7]
Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' supports one-to-many and many-to-one
semantics. The precise semantics depend on the socket type and are defined in
linkzmq:zmq_socket[3].
NOTE: for most transports and socket types the connection is not performed
immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_
does not mean that the connection was or could actually be established.
Because of this, for most transports and socket types the order in which
a 'server' socket is bound and a 'client' socket is connected to it does not
matter. The _ZMQ_PAIR_ and _ZMQ_CHANNEL_ sockets are an exception, as they do not automatically
reconnect to endpoints.
NOTE: following a _zmq_connect()_, for socket types except for ZMQ_ROUTER,
the socket enters its normal 'ready' state. By contrast, following a
_zmq_bind()_ alone, the socket enters a 'mute' state in which the socket
blocks or drops messages according to the socket type, as defined in
linkzmq:zmq_socket[3]. A ZMQ_ROUTER socket enters its normal 'ready' state
for a specific peer only when handshaking is complete for that peer, which
may take an arbitrary time.
NOTE: for some socket types, multiple connections to the same endpoint
don't really make sense
(see https://github.com/zeromq/libzmq/issues/788).
For those socket types, any attempt to connect to an already connected endpoint
is silently ignored (i.e., returns zero). This behavior applies to ZMQ_DEALER,
ZMQ_SUB, ZMQ_PUB, and ZMQ_REQ socket types.
RETURN VALUE
------------
The _zmq_connect()_ function returns zero if successful. Otherwise it returns
`-1` and sets 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.
EXAMPLE
-------
.Connecting a subscriber socket to an in-process and a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to an in-process transport with the address 'my_publisher' */
int rc = zmq_connect (socket, "inproc://my_publisher");
assert (rc == 0);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

92
vendor/ZMQ/doc/zmq_connect_peer.txt vendored Normal file
View File

@@ -0,0 +1,92 @@
zmq_connect_peer(3)
===================
NAME
----
zmq_connect_peer - create outgoing connection from socket and return the connection routing id in thread-safe and atomic way.
SYNOPSIS
--------
*uint32_t zmq_connect_peer (void '*socket', const char '*endpoint');*
DESCRIPTION
-----------
The _zmq_connect_peer()_ function connects a 'ZMQ_PEER' socket to an 'endpoint' and then returns the endpoint 'routing_id'.
The 'endpoint' is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
The function is supported only on the 'ZMQ_PEER' socket type and would return `0` with 'errno' set to 'ENOTSUP' otherwise.
The _zmq_connect_peer()_ support the following transports:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'ws':: unicast transport using WebSockets, see linkzmq:zmq_ws[7]
'wss':: unicast transport using WebSockets over TLS, see linkzmq:zmq_wss[7]
RETURN VALUE
------------
The _zmq_connect_peer()_ function returns the peer 'routing_id' if successful. Otherwise it returns
`0` and sets 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported with 'ZMQ_PEER'.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.
*ENOTSUP*::
The socket is not of type 'ZMQ_PEER'.
*EFAULT*::
The 'ZMQ_IMMEDIATE' option is set on the socket.
EXAMPLE
-------
.Connecting a peer socket to a TCP transport and sending a message
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_PEER);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
uint32_t routing_id = zmq_connect (socket, "tcp://server001:5555");
assert (routing_id == 0);
/* Sending a message to the peer */
zmq_msg_t msg;
int rc = zmq_msg_init_data (&msg, "HELLO", 5, NULL, NULL);
assert (rc == 0);
rc = zmq_msg_set_routing_id (&msg, routing_id);
assert (rc == 0);
rc = zmq_msg_send (&msg, socket, 0);
assert (rc == 5);
rc = zmq_msg_close (&msg);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

67
vendor/ZMQ/doc/zmq_ctx_destroy.txt vendored Normal file
View File

@@ -0,0 +1,67 @@
zmq_ctx_destroy(3)
==================
NAME
----
zmq_ctx_destroy - terminate a 0MQ context
SYNOPSIS
--------
*int zmq_ctx_destroy (void '*context');*
DESCRIPTION
-----------
The _zmq_ctx_destroy()_ function shall destroy the 0MQ context 'context'.
Context termination is performed in the following steps:
1. Any blocking operations currently in progress on sockets open within
'context' shall return immediately with an error code of ETERM. With the
exception of _zmq_close()_, any further operations on sockets open within
'context' shall fail with an error code of ETERM.
2. After interrupting all blocking calls, _zmq_ctx_destroy()_ shall _block_ until the
following conditions are satisfied:
* All sockets open within 'context' have been closed with _zmq_close()_.
* For each socket within 'context', all messages sent by the application
with _zmq_send()_ have either been physically transferred to a network
peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
option has expired.
For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
option in linkzmq:zmq_setsockopt[3].
This function is deprecated by linkzmq:zmq_ctx_term[3].
RETURN VALUE
------------
The _zmq_ctx_destroy()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
The provided 'context' was invalid.
*EINTR*::
Termination was interrupted by a signal. It can be restarted if needed.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]
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>.

125
vendor/ZMQ/doc/zmq_ctx_get.txt vendored Normal file
View File

@@ -0,0 +1,125 @@
zmq_ctx_get(3)
==============
NAME
----
zmq_ctx_get - get context options
SYNOPSIS
--------
*int zmq_ctx_get (void '*context', int 'option_name');*
DESCRIPTION
-----------
The _zmq_ctx_get()_ function shall return the option specified by the
'option_name' argument.
The _zmq_ctx_get()_ function accepts the following option names:
ZMQ_IO_THREADS: Get number of I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IO_THREADS' argument returns the size of the 0MQ thread pool
for this context.
ZMQ_MAX_SOCKETS: Get maximum number of sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_SOCKETS' argument returns the maximum number of sockets
allowed for this context.
ZMQ_MAX_MSGSZ: Get maximum message size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_MSGSZ' argument returns the maximum size of a message
allowed for this context. Default value is INT_MAX.
ZMQ_ZERO_COPY_RECV: Get message decoding strategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ZERO_COPY_RECV' argument return whether message decoder uses a zero copy
strategy when receiving messages. Default value is 1.
NOTE: in DRAFT state, not yet available in stable releases.
ZMQ_SOCKET_LIMIT: Get largest configurable number of sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SOCKET_LIMIT' argument returns the largest number of sockets that
linkzmq:zmq_ctx_set[3] will accept.
ZMQ_IPV6: Set IPv6 option
~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IPV6' argument returns the IPv6 option for the context.
ZMQ_BLOCKY: Get blocky setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_BLOCKY' argument returns 1 if the context will block on terminate,
zero if the "block forever on context termination" gambit was disabled by
setting ZMQ_BLOCKY to false on all new contexts.
ZMQ_THREAD_SCHED_POLICY: Get scheduling policy for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_SCHED_POLICY' argument returns the scheduling policy for
internal context's thread pool.
ZMQ_THREAD_NAME_PREFIX: Get name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument gets the numeric prefix of each thread
created for the internal context's thread pool.
ZMQ_MSG_T_SIZE: Get the zmq_msg_t size at runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MSG_T_SIZE' argument returns the size of the zmq_msg_t structure at
runtime, as defined in the include/zmq.h public header.
This is useful for example for FFI bindings that can't simply do a sizeof().
RETURN VALUE
------------
The _zmq_ctx_get()_ function returns a value of 0 or greater if successful.
Otherwise it returns `-1` and sets 'errno' to one of the values defined
below.
ERRORS
------
*EINVAL*::
The requested option _option_name_ is unknown.
*EFAULT*::
The provided 'context' is invalid.
EXAMPLE
-------
.Setting a limit on the number of sockets
----
void *context = zmq_ctx_new ();
zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
assert (max_sockets == 256);
----
.Switching off the context deadlock gambit
----
zmq_ctx_set (ctx, ZMQ_BLOCKY, false);
----
SEE ALSO
--------
linkzmq:zmq_ctx_set[3]
linkzmq:zmq[7]
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>.

84
vendor/ZMQ/doc/zmq_ctx_get_ext.txt vendored Normal file
View File

@@ -0,0 +1,84 @@
zmq_ctx_get_ext(3)
==================
NAME
----
zmq_ctx_get_ext - get extended context options
SYNOPSIS
--------
*int zmq_ctx_get_ext (void '*context', int 'option_name', void '*option_value', size_t '*option_len');*
DESCRIPTION
-----------
The _zmq_ctx_get()_ function shall retrieve the value for the option
specified by the 'option_name' argument and store it in the buffer pointed to
by the 'option_value' argument.
The 'option_len' argument is the size in bytes of the buffer pointed
to by 'option_value'; upon successful completion _zmq_ctx_get_ext()_ shall
modify the 'option_len' argument to indicate the actual size of the option
value stored in the buffer.
The _zmq_ctx_get_ext()_ function accepts all the option names accepted by
_zmq_ctx_get()_.
Options that make most sense to retrieve using _zmq_ctx_get_ext()_ instead of
_zmq_ctx_get()_ are:
ZMQ_THREAD_NAME_PREFIX: Get name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument gets the string prefix of each thread
created for the internal context's thread pool.
[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: empty string
RETURN VALUE
------------
The _zmq_ctx_get_ext()_ function returns a value of 0 or greater if successful.
Otherwise it returns `-1` and sets 'errno' to one of the values defined
below.
ERRORS
------
*EINVAL*::
The requested option _option_name_ is unknown.
*EFAULT*::
The provided 'context' is invalid.
EXAMPLE
-------
.Setting a prefix on internal ZMQ thread names:
----
void *context = zmq_ctx_new ();
const char prefix[] = "MyApp";
size_t prefixLen = sizeof(prefix);
zmq_ctx_set (context, ZMQ_THREAD_NAME_PREFIX, &prefix, &prefixLen);
char buff[256];
size_t buffLen = sizeof(buff);
int rc = zmq_ctx_get (context, ZMQ_THREAD_NAME_PREFIX, &buff, &buffLen);
assert (rc == 0);
assert (buffLen == prefixLen);
----
SEE ALSO
--------
linkzmq:zmq_ctx_get[3]
linkzmq:zmq[7]
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>.

55
vendor/ZMQ/doc/zmq_ctx_new.txt vendored Normal file
View File

@@ -0,0 +1,55 @@
zmq_ctx_new(3)
==============
NAME
----
zmq_ctx_new - create new 0MQ context
SYNOPSIS
--------
*void *zmq_ctx_new ();*
DESCRIPTION
-----------
The _zmq_ctx_new()_ function creates a new 0MQ 'context'.
This function replaces the deprecated function linkzmq:zmq_init[3].
.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.
RETURN VALUE
------------
The _zmq_ctx_new()_ function shall return an opaque handle to the newly created
'context' if successful. Otherwise it shall return NULL and set 'errno' to one
of the values defined below.
ERRORS
------
*EMFILE*::
The limit on the total number of open files has been reached and it
wasn't possible to create a new context.
*EMFILE*::
The limit on the total number of open files in system has been reached
and it wasn't possible to create a new context.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_ctx_set[3]
linkzmq:zmq_ctx_get[3]
linkzmq:zmq_ctx_term[3]
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>.

197
vendor/ZMQ/doc/zmq_ctx_set.txt vendored Normal file
View File

@@ -0,0 +1,197 @@
zmq_ctx_set(3)
==============
NAME
----
zmq_ctx_set - set context options
SYNOPSIS
--------
*int zmq_ctx_set (void '*context', int 'option_name', int 'option_value');*
DESCRIPTION
-----------
The _zmq_ctx_set()_ function shall set the option specified by the
'option_name' argument to the value of the 'option_value' argument.
The _zmq_ctx_set()_ function accepts the following options:
ZMQ_BLOCKY: Fix blocky behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default the context will block, forever, on a zmq_ctx_term call. The
assumption behind this behavior is that abrupt termination will cause
message loss. Most real applications use some form of handshaking to ensure
applications receive termination messages, and then terminate the context
with 'ZMQ_LINGER' set to zero on all sockets. This setting is an easier way
to get the same result. When 'ZMQ_BLOCKY' is set to false, all new sockets
are given a linger timeout of zero. You must still close all sockets before
calling zmq_ctx_term.
[horizontal]
Default value:: true (old behavior)
ZMQ_IO_THREADS: Set number of I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IO_THREADS' argument specifies the size of the 0MQ thread pool to
handle I/O operations. If your application is using only the 'inproc'
transport for messaging you may set this to zero, otherwise set it to at
least one. This option only applies before creating any sockets on the
context.
[horizontal]
Default value:: 1
ZMQ_THREAD_SCHED_POLICY: Set scheduling policy for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_SCHED_POLICY' argument sets the scheduling policy for
internal context's thread pool. This option is not available on windows.
Supported values for this option can be found in sched.h file,
or at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html.
This option only applies before creating any sockets on the context.
[horizontal]
Default value:: -1
ZMQ_THREAD_PRIORITY: Set scheduling priority for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_PRIORITY' argument sets scheduling priority for
internal context's thread pool. This option is not available on windows.
Supported values for this option depend on chosen scheduling policy.
On Linux, when the scheduler policy is SCHED_OTHER, SCHED_IDLE or SCHED_BATCH, the OS scheduler
will not use the thread priority but rather the thread "nice value"; in such cases
the system call "nice" will be used to set the nice value to -20 (max priority) instead of
adjusting the thread priority (which must be zero for those scheduling policies).
Details can be found in sched.h file, or at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html.
This option only applies before creating any sockets on the context.
[horizontal]
Default value:: -1
ZMQ_THREAD_AFFINITY_CPU_ADD: Add a CPU to list of affinity for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_AFFINITY_CPU_ADD' argument adds a specific CPU to the affinity list for the internal
context's thread pool. This option is only supported on Linux.
This option only applies before creating any sockets on the context.
The default affinity list is empty and means that no explicit CPU-affinity will be set on
internal context's threads.
[horizontal]
Default value:: -1
ZMQ_THREAD_AFFINITY_CPU_REMOVE: Remove a CPU to list of affinity for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_AFFINITY_CPU_REMOVE' argument removes a specific CPU to the affinity list for the internal
context's thread pool. This option is only supported on Linux.
This option only applies before creating any sockets on the context.
The default affinity list is empty and means that no explicit CPU-affinity will be set on
internal context's threads.
[horizontal]
Default value:: -1
ZMQ_THREAD_NAME_PREFIX: Set name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument sets a numeric prefix to each thread
created for the internal context's thread pool. This option is only supported on Linux.
This option is useful to help debugging done via "top -H" or "gdb"; in case
multiple processes on the system are using ZeroMQ it is useful to provide through
this context option an application-specific prefix to distinguish ZeroMQ background
threads that belong to different processes.
This option only applies before creating any sockets on the context.
[horizontal]
Default value:: -1
ZMQ_MAX_MSGSZ: Set maximum message size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_MSGSZ' argument sets the maximum allowed size
of a message sent in the context. You can query the maximal
allowed value with linkzmq:zmq_ctx_get[3] using the
'ZMQ_MAX_MSGSZ' option.
[horizontal]
Default value:: INT_MAX
Maximum value:: INT_MAX
ZMQ_ZERO_COPY_RECV: Specify message decoding strategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ZERO_COPY_RECV' argument specifies whether the message decoder should
use a zero copy strategy when receiving messages. The zero copy strategy can
lead to increased memory usage in some cases. This option allows you to use the
older copying strategy. You can query the value of this option with
linkzmq:zmq_ctx_get[3] using the 'ZMQ_ZERO_COPY_RECV' option.
NOTE: in DRAFT state, not yet available in stable releases.
[horizontal]
Default value:: 1
ZMQ_MAX_SOCKETS: Set maximum number of sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_SOCKETS' argument sets the maximum number of sockets allowed
on the context. You can query the maximal allowed value with
linkzmq:zmq_ctx_get[3] using the 'ZMQ_SOCKET_LIMIT' option.
[horizontal]
Default value:: 1023
ZMQ_IPV6: Set IPv6 option
~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IPV6' argument sets the IPv6 value for all sockets created in
the context from this point onwards. A value of `1` means IPv6 is
enabled, while `0` means the socket will use only IPv4. When IPv6 is
enabled, a socket will connect to, or accept connections from, both
IPv4 and IPv6 hosts.
[horizontal]
Default value:: 0
RETURN VALUE
------------
The _zmq_ctx_set()_ function returns zero if successful. Otherwise it
returns `-1` and sets 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The requested option _option_name_ is unknown.
EXAMPLE
-------
.Setting a limit on the number of sockets
----
void *context = zmq_ctx_new ();
zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
assert (max_sockets == 256);
----
SEE ALSO
--------
linkzmq:zmq_ctx_get[3]
linkzmq:zmq[7]
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>.

88
vendor/ZMQ/doc/zmq_ctx_set_ext.txt vendored Normal file
View File

@@ -0,0 +1,88 @@
zmq_ctx_set_ext(3)
==================
NAME
----
zmq_ctx_set_ext - set extended context options
SYNOPSIS
--------
*int zmq_ctx_set_ext (void '*context', int 'option_name', const void '*option_value', size_t 'option_len');*
DESCRIPTION
-----------
The _zmq_ctx_set_ext()_ function shall set the option specified by the
'option_name' argument to the value pointed to by the 'option_value' argument
for the 0MQ context pointed to by the 'context' argument. The 'option_len'
argument is the size of the option value in bytes. For options taking a value of
type "character string", the provided byte data should either contain no zero
bytes, or end in a single zero byte (terminating ASCII NUL character).
The _zmq_ctx_set_ext()_ function accepts all the option names accepted by
_zmq_ctx_set()_.
Options that make most sense to set using _zmq_ctx_set_ext()_ instead of
_zmq_ctx_set()_ are the following options:
ZMQ_THREAD_NAME_PREFIX: Set name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument sets a string prefix to each thread
created for the internal context's thread pool. This option is only supported on Linux.
This option is useful to help debugging done via "top -H" or "gdb"; in case
multiple processes on the system are using ZeroMQ it is useful to provide through
this context option an application-specific prefix to distinguish ZeroMQ background
threads that belong to different processes.
This option only applies before creating any sockets on the context.
[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: empty string
RETURN VALUE
------------
The _zmq_ctx_set_ext()_ function returns zero if successful. Otherwise it
returns `-1` and sets 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The requested option _option_name_ is unknown.
*EFAULT*::
The provided 'context' is invalid.
EXAMPLE
-------
.Setting a prefix on internal ZMQ thread names:
----
void *context = zmq_ctx_new ();
const char prefix[] = "MyApp";
size_t prefixLen = sizeof(prefix);
zmq_ctx_set (context, ZMQ_THREAD_NAME_PREFIX, &prefix, &prefixLen);
char buff[256];
size_t buffLen = sizeof(buff);
int rc = zmq_ctx_get (context, ZMQ_THREAD_NAME_PREFIX, &buff, &buffLen);
assert (rc == 0);
assert (buffLen == prefixLen);
----
SEE ALSO
--------
linkzmq:zmq_ctx_set[3]
linkzmq:zmq[7]
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>.

54
vendor/ZMQ/doc/zmq_ctx_shutdown.txt vendored Normal file
View File

@@ -0,0 +1,54 @@
zmq_ctx_shutdown(3)
==================
NAME
----
zmq_ctx_shutdown - shutdown a 0MQ context
SYNOPSIS
--------
*int zmq_ctx_shutdown (void '*context');*
DESCRIPTION
-----------
The _zmq_ctx_shutdown()_ function shall shutdown the 0MQ context 'context'.
Context shutdown will cause any blocking operations currently in progress on
sockets open within 'context' to return immediately with an error code of ETERM.
With the exception of _zmq_close()_, any further operations on sockets open within
'context' shall fail with an error code of ETERM. No further sockets can be created
using _zmq_socket()_ on a context for which _zmq_ctx_shutdown()_ has been called,
it will return and set errno to ETERM.
This function is optional, client code is still required to call the linkzmq:zmq_ctx_term[3]
function to free all resources allocated by zeromq.
RETURN VALUE
------------
The _zmq_ctx_shutdown()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
The provided 'context' was invalid.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_ctx_term[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]
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>.

68
vendor/ZMQ/doc/zmq_ctx_term.txt vendored Normal file
View File

@@ -0,0 +1,68 @@
zmq_ctx_term(3)
===============
NAME
----
zmq_ctx_term - terminate a 0MQ context
SYNOPSIS
--------
*int zmq_ctx_term (void '*context');*
DESCRIPTION
-----------
The _zmq_ctx_term()_ function shall destroy the 0MQ context 'context'.
Context termination is performed in the following steps:
1. Any blocking operations currently in progress on sockets open within
'context' shall return immediately with an error code of ETERM. With the
exception of _zmq_close()_, any further operations on sockets open within
'context' shall fail with an error code of ETERM.
2. After interrupting all blocking calls, _zmq_ctx_term()_ shall _block_ until
the following conditions are satisfied:
* All sockets open within 'context' have been closed with _zmq_close()_.
* For each socket within 'context', all messages sent by the application
with _zmq_send()_ have either been physically transferred to a network
peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
option has expired.
For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
option in linkzmq:zmq_setsockopt[3].
This function replaces the deprecated functions linkzmq:zmq_term[3] and
linkzmq:zmq_ctx_destroy[3].
RETURN VALUE
------------
The _zmq_ctx_term()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
The provided 'context' was invalid.
*EINTR*::
Termination was interrupted by a signal. It can be restarted if needed.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]
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>.

92
vendor/ZMQ/doc/zmq_curve.txt vendored Normal file
View File

@@ -0,0 +1,92 @@
zmq_curve(7)
============
NAME
----
zmq_curve - secure authentication and confidentiality
SYNOPSIS
--------
The CURVE mechanism defines a mechanism for secure authentication and
confidentiality for communications between a client and a server. CURVE
is intended for use on public networks. The CURVE mechanism is defined
by this document: <http://rfc.zeromq.org/spec:25>.
CLIENT AND SERVER ROLES
-----------------------
A socket using CURVE can be either client or server, at any moment, but
not both. The role is independent of bind/connect direction.
A socket can change roles at any point by setting new options. The role
affects all zmq_connect and zmq_bind calls that follow it.
To become a CURVE server, the application sets the ZMQ_CURVE_SERVER option
on the socket, and then sets the ZMQ_CURVE_SECRETKEY option to provide the
socket with its long-term secret key. The application does not provide the
socket with its long-term public key, which is used only by clients.
To become a CURVE client, the application sets the ZMQ_CURVE_SERVERKEY
option with the long-term public key of the server it intends to connect
to, or accept connections from, next. The application then sets the
ZMQ_CURVE_PUBLICKEY and ZMQ_CURVE_SECRETKEY options with its client
long-term key pair.
If the server does authentication it will be based on the client's long
term public key.
KEY ENCODING
------------
The standard representation for keys in source code is either 32 bytes of
base 256 (binary) data, or 40 characters of base 85 data encoded using the
Z85 algorithm defined by http://rfc.zeromq.org/spec:32.
The Z85 algorithm is designed to produce printable key strings for use in
configuration files, the command line, and code. There is a reference
implementation in C at https://github.com/zeromq/rfc/tree/master/src.
TEST KEY VALUES
---------------
For test cases, the client shall use this long-term key pair (specified
as hexadecimal and in Z85):
----
public:
BB88471D65E2659B30C55A5321CEBB5AAB2B70A398645C26DCA2B2FCB43FC518
Yne@$w-vo<fVvi]a<NY6T1ed:M$fCG*[IaLV{hID
secret:
7BB864B489AFA3671FBE69101F94B38972F24816DFB01B51656B3FEC8DFD0888
D:)Q[IlAW!ahhC2ac:9*A}h:p?([4%wOTJ%JR%cs
----
And the server shall use this long-term key pair (specified as hexadecimal
and in Z85):
----
public:
54FCBA24E93249969316FB617C872BB0C1D1FF14800427C594CBFACF1BC2D652
rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7
secret:
8E0BDD697628B91D8F245587EE95C5B04D48963F79259877B49CD9063AEAD3B7
JTKVSB%%)wK0E.X)V>+}o?pNmC{O&4W4b!Ni{Lh6
----
SEE ALSO
--------
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_plain[7]
linkzmq:zmq[7]
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>.

56
vendor/ZMQ/doc/zmq_curve_keypair.txt vendored Normal file
View File

@@ -0,0 +1,56 @@
zmq_curve_keypair(3)
====================
NAME
----
zmq_curve_keypair - generate a new CURVE keypair
SYNOPSIS
--------
*int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key);*
DESCRIPTION
-----------
The _zmq_curve_keypair()_ function shall return a newly generated random
keypair consisting of a public key and a secret key. The caller provides
two buffers, each at least 41 octets large, in which this method will
store the keys. The keys are encoded using linkzmq:zmq_z85_encode[3].
RETURN VALUE
------------
The _zmq_curve_keypair()_ function shall return 0 if successful, else it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOTSUP*::
The libzmq library was not built with cryptographic support (libsodium).
EXAMPLE
-------
.Generating a new CURVE keypair
----
char public_key [41];
char secret_key [41];
int rc = zmq_curve_keypair (public_key, secret_key);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_curve[7]
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>.

62
vendor/ZMQ/doc/zmq_curve_public.txt vendored Normal file
View File

@@ -0,0 +1,62 @@
zmq_curve_public(3)
===================
NAME
----
zmq_curve_public - derive the public key from a private key
SYNOPSIS
--------
*int zmq_curve_public (char *z85_public_key, char *z85_secret_key);*
DESCRIPTION
-----------
The _zmq_curve_public()_ function shall derive the public key from a
private key. The caller provides two buffers, each at least 41 octets
large. In z85_secret_key the caller shall provide the private key, and
the function will store the public key in z85_public_key. The keys are
encoded using linkzmq:zmq_z85_encode[3].
RETURN VALUE
------------
The _zmq_curve_public()_ function shall return 0 if successful, else it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOTSUP*::
The libzmq library was not built with cryptographic support (libsodium).
EXAMPLE
-------
.Deriving the public key from a CURVE private key
----
char public_key [41];
char secret_key [41];
int rc = zmq_curve_keypair (public_key, secret_key);
assert (rc == 0);
char derived_public[41];
rc = zmq_curve_public (derived_public, secret_key);
assert (rc == 0);
assert (!strcmp (derived_public, public_key));
----
SEE ALSO
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve[7]
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>.

76
vendor/ZMQ/doc/zmq_disconnect.txt vendored Normal file
View File

@@ -0,0 +1,76 @@
zmq_disconnect(3)
=================
NAME
----
zmq_disconnect - Disconnect a socket from an endpoint
SYNOPSIS
--------
*int zmq_disconnect (void '*socket', const char '*endpoint');*
DESCRIPTION
-----------
The _zmq_disconnect()_ function shall disconnect a socket specified
by the 'socket' argument from the endpoint specified by the 'endpoint'
argument. Note the actual disconnect system call might occur at a later time.
Upon disconnection the will also stop receiving messages originating from
this endpoint. Moreover, the socket will no longuer be able
to queue outgoing messages to this endpoint. The outgoing message queue
associated with the endpoint will be discarded. However, if the socket's linger
period is non-zero, libzmq will still attempt to transmit these discarded messages,
until the linger period expires.
The 'endpoint' argument is as described in linkzmq:zmq_connect[3]
NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
this behaviour may cause the application to block when calling _zmq_ctx_term()_.
For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3].
RETURN VALUE
------------
The _zmq_disconnect()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ENOENT*::
The provided endpoint is not in use by the socket.
EXAMPLE
-------
.Connecting a subscriber socket to an in-process and a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_disconnect (socket, "tcp://server001:5555");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

50
vendor/ZMQ/doc/zmq_errno.txt vendored Normal file
View File

@@ -0,0 +1,50 @@
zmq_errno(3)
============
NAME
----
zmq_errno - retrieve value of errno for the calling thread
SYNOPSIS
--------
*int zmq_errno (void);*
DESCRIPTION
-----------
The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for
the calling thread.
The _zmq_errno()_ function is provided to assist users on non-POSIX systems who
are experiencing issues with retrieving the correct value of 'errno' directly.
Specifically, users on Win32 systems whose application is using a different C
run-time library from the C run-time library in use by 0MQ will need to use
_zmq_errno()_ for correct operation.
IMPORTANT: Users not experiencing issues with retrieving the correct value of
'errno' should not use this function and should instead access the 'errno'
variable directly.
RETURN VALUE
------------
The _zmq_errno()_ function shall return the value of the 'errno' variable for
the calling thread.
ERRORS
------
No errors are defined.
SEE ALSO
--------
linkzmq:zmq[7]
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>.

1030
vendor/ZMQ/doc/zmq_getsockopt.txt vendored Normal file
View File

File diff suppressed because it is too large Load Diff

78
vendor/ZMQ/doc/zmq_gssapi.txt vendored Normal file
View File

@@ -0,0 +1,78 @@
zmq_gssapi(7)
============
NAME
----
zmq_gssapi - secure authentication and confidentiality
SYNOPSIS
--------
The GSSAPI mechanism defines a mechanism for secure authentication and
confidentiality for communications between a client and a server using the
Generic Security Service Application Program Interface (GSSAPI). The GSSAPI
mechanism can be used on both public and private networks. GSSAPI itself is
defined in IETF RFC-2743: <http://tools.ietf.org/html/rfc2743>. The ZeroMQ
GSSAPI mechanism is defined by this document: <http://rfc.zeromq.org/spec:38>.
CLIENT AND SERVER ROLES
-----------------------
A socket using GSSAPI can be either client or server, but not both.
To become a GSSAPI server, the application sets the ZMQ_GSSAPI_SERVER
option on the socket.
To become a GSSAPI client, the application sets the ZMQ_GSSAPI_SERVICE_PRINCIPAL
option to the name of the principal on the server to which it intends to
connect.
On client or server, the application may additionally set the
ZMQ_GSSAPI_PRINCIPAL option to provide the socket with the name of the
principal for whom GSSAPI credentials should be acquired. If this option
is not set, default credentials are used.
OPTIONAL ENCRYPTION
-------------------
By default, the GSSAPI mechanism will encrypt all communications between client
and server. If encryption is not desired (e.g. on private networks), the
client and server applications can disable it by setting the
ZMQ_GSSAPI_PLAINTEXT option. Both the client and server must set this option
to the same value.
PRINCIPAL NAMES
---------------
Principal names specified with the ZMQ_GSSAPI_SERVICE_PRINCIPAL or
ZMQ_GSSAPI_PRINCIPAL options are interpreted as "host based" name types
by default. The ZMQ_GSSAPI_PRINCIPAL_NAMETYPE and
ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE options may be used to change the
name type to one of:
*ZMQ_GSSAPI_NT_HOSTBASED*::
The name should be of the form "service" or "service@hostname",
which will parse into a principal of "service/hostname"
in the local realm. This is the default name type.
*ZMQ_GSSAPI_NT_USER_NAME*::
The name should be a local username, which will parse into a single-component
principal in the local realm.
*ZMQ_GSSAPI_NT_KRB5_PRINCIPAL*::
The name is a principal name string. This name type only works with
the krb5 GSSAPI mechanism.
SEE ALSO
--------
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]
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>.

44
vendor/ZMQ/doc/zmq_has.txt vendored Normal file
View File

@@ -0,0 +1,44 @@
zmq_has(3)
==========
NAME
----
zmq_has - check a ZMQ capability
SYNOPSIS
--------
*int zmq_has (const char *capability);*
DESCRIPTION
-----------
The _zmq_has()_ function shall report whether a specified capability is
available in the library. This allows bindings and applications to probe
a library directly, for transport and security options.
Capabilities shall be lowercase strings. The following capabilities are
defined:
* ipc - the library supports the ipc:// protocol
* pgm - the library supports the pgm:// protocol
* tipc - the library supports the tipc:// protocol
* norm - the library supports the norm:// protocol
* curve - the library supports the CURVE security mechanism
* gssapi - the library supports the GSSAPI security mechanism
* draft - the library is built with the draft api
When this method is provided, the zmq.h header file will define
ZMQ_HAS_CAPABILITIES.
RETURN VALUE
------------
The _zmq_has()_ function shall return 1 if the specified capability is
provided. Otherwise it shall return 0.
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>.

52
vendor/ZMQ/doc/zmq_init.txt vendored Normal file
View File

@@ -0,0 +1,52 @@
zmq_init(3)
===========
NAME
----
zmq_init - initialise 0MQ context
SYNOPSIS
--------
*void *zmq_init (int 'io_threads');*
DESCRIPTION
-----------
The _zmq_init()_ function initialises a 0MQ 'context'.
The 'io_threads' argument specifies the size of the 0MQ thread pool to handle
I/O operations. If your application is using only the 'inproc' transport for
messaging you may set this to zero, otherwise set it to at least one.
.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.
This function is deprecated by linkzmq:zmq_ctx_new[3].
RETURN VALUE
------------
The _zmq_init()_ function shall return an opaque handle to the initialised
'context' if successful. Otherwise it shall return NULL and set 'errno' to one
of the values defined below.
ERRORS
------
*EINVAL*::
An invalid number of 'io_threads' was requested.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_ctx_term[3]
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>.

88
vendor/ZMQ/doc/zmq_inproc.txt vendored Normal file
View File

@@ -0,0 +1,88 @@
zmq_inproc(7)
=============
NAME
----
zmq_inproc - 0MQ local in-process (inter-thread) communication transport
SYNOPSIS
--------
The in-process transport passes messages via memory directly between threads
sharing a single 0MQ 'context'.
NOTE: No I/O threads are involved in passing messages using the 'inproc'
transport. Therefore, if you are using a 0MQ 'context' for in-process messaging
only you can initialise the 'context' with zero I/O threads. See
linkzmq:zmq_init[3] for details.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the in-process transport, the transport is `inproc`, and the meaning of
the 'address' part is defined below.
Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a 'socket' using _zmq_bind()_ with the
'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'name' to create. The 'name' must be unique within the 0MQ
'context' associated with the 'socket' and may be up to 256 characters in
length. No other restrictions are placed on the format of the 'name'.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a 'socket' to a peer address using _zmq_connect()_ with the
'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'name' to connect to. Before version 4.0 he 'name' must have
been previously created by assigning it to at least one 'socket' within the
same 0MQ 'context' as the 'socket' being connected. Since version 4.0 the
order of _zmq_bind()_ and _zmq_connect()_ does not matter just like for the tcp
transport type.
EXAMPLES
--------
.Assigning a local address to a socket
----
// Assign the in-process name "#1"
rc = zmq_bind(socket, "inproc://#1");
assert (rc == 0);
// Assign the in-process name "my-endpoint"
rc = zmq_bind(socket, "inproc://my-endpoint");
assert (rc == 0);
----
.Connecting a socket
----
// Connect to the in-process name "#1"
rc = zmq_connect(socket, "inproc://#1");
assert (rc == 0);
// Connect to the in-process name "my-endpoint"
rc = zmq_connect(socket, "inproc://my-endpoint");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_ipc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]
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>.

106
vendor/ZMQ/doc/zmq_ipc.txt vendored Normal file
View File

@@ -0,0 +1,106 @@
zmq_ipc(7)
==========
NAME
----
zmq_ipc - 0MQ local inter-process communication transport
SYNOPSIS
--------
The inter-process transport passes messages between local processes using a
system-dependent IPC mechanism.
NOTE: The inter-process transport is currently only implemented on operating
systems that provide UNIX domain sockets.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the inter-process transport, the transport is `ipc`, and the meaning of
the 'address' part is defined below.
Binding a socket
~~~~~~~~~~~~~~~~
When binding a 'socket' to a local address using _zmq_bind()_ with the 'ipc'
transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'pathname' to create. The 'pathname' must be unique within the
operating system namespace used by the 'ipc' implementation, and must fulfill
any restrictions placed by the operating system on the format and length of a
'pathname'.
When the address is wild-card `*`, _zmq_bind()_ shall generate a unique temporary
pathname. The caller should retrieve this pathname using the ZMQ_LAST_ENDPOINT
socket option. See linkzmq:zmq_getsockopt[3] for details.
NOTE: any existing binding to the same endpoint shall be overridden. That is,
if a second process binds to an endpoint already bound by a process, this
will succeed and the first process will lose its binding. In this behaviour,
the 'ipc' transport is not consistent with the 'tcp' or 'inproc' transports.
NOTE: the endpoint pathname must be writable by the process. When the endpoint
starts with '/', e.g., `ipc:///pathname`, this will be an _absolute_ pathname.
If the endpoint specifies a directory that does not exist, the bind shall fail.
NOTE: on Linux only, when the endpoint pathname starts with `@`, the abstract
namespace shall be used. The abstract namespace is independent of the
filesystem and if a process attempts to bind an endpoint already bound by a
process, it will fail. See unix(7) for details.
NOTE: IPC pathnames have a maximum size that depends on the operating system.
On Linux, the maximum is 113 characters including the "ipc://" prefix (107
characters for the real path name).
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a 'socket' to a peer address using _zmq_connect()_ with the
'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'pathname' to connect to. The 'pathname' must have been
previously created within the operating system namespace by assigning it to a
'socket' with _zmq_bind()_.
EXAMPLES
--------
.Assigning a local address to a socket
----
// Assign the pathname "/tmp/feeds/0"
rc = zmq_bind(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
----
.Connecting a socket
----
// Connect to the pathname "/tmp/feeds/0"
rc = zmq_connect(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq[7]
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>.

57
vendor/ZMQ/doc/zmq_msg_close.txt vendored Normal file
View File

@@ -0,0 +1,57 @@
zmq_msg_close(3)
================
NAME
----
zmq_msg_close - release 0MQ message
SYNOPSIS
--------
*int zmq_msg_close (zmq_msg_t '*msg');*
DESCRIPTION
-----------
The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any
resources associated with the message object referenced by 'msg' are no longer
required and may be released. Actual release of resources associated with the
message object shall be postponed by 0MQ until all users of the message or
underlying data buffer have indicated it is no longer required.
Applications should ensure that _zmq_msg_close()_ is called once a message is
no longer required, otherwise memory leaks may occur. Note that this is NOT
necessary after a successful _zmq_msg_send()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
The _zmq_msg_close()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
Invalid message.
SEE ALSO
--------
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
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>.

72
vendor/ZMQ/doc/zmq_msg_copy.txt vendored Normal file
View File

@@ -0,0 +1,72 @@
zmq_msg_copy(3)
===============
NAME
----
zmq_msg_copy - copy content of a message to another message
SYNOPSIS
--------
*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION
-----------
The _zmq_msg_copy()_ function shall copy the message object referenced by 'src'
to the message object referenced by 'dest'. The original content of 'dest', if
any, shall be released. You must initialise 'dest' before copying to it.
CAUTION: The implementation may choose not to physically copy the message
content, rather to share the underlying buffer between 'src' and 'dest'. Avoid
modifying message content after a message has been copied with
_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need
is an actual hard copy, initialize a new message using _zmq_msg_init_buffer()_
with the message content.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
Invalid message.
EXAMPLE
-------
.Copying a message
----
zmq_msg_t msg;
zmq_msg_init_buffer (&msg, "Hello, World", 12);
zmq_msg_t copy;
zmq_msg_init (&copy);
zmq_msg_copy (&copy, &msg);
...
zmq_msg_close (&copy);
zmq_msg_close (&msg);
----
SEE ALSO
--------
linkzmq:zmq_msg_move[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

49
vendor/ZMQ/doc/zmq_msg_data.txt vendored Normal file
View File

@@ -0,0 +1,49 @@
zmq_msg_data(3)
===============
NAME
----
zmq_msg_data - retrieve pointer to message content
SYNOPSIS
--------
*void *zmq_msg_data (zmq_msg_t '*msg');*
DESCRIPTION
-----------
The _zmq_msg_data()_ function shall return a pointer to the message content of
the message object referenced by 'msg'.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
Upon successful completion, _zmq_msg_data()_ shall return a pointer to the
message content.
ERRORS
------
No errors are defined.
SEE ALSO
--------
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

83
vendor/ZMQ/doc/zmq_msg_get.txt vendored Normal file
View File

@@ -0,0 +1,83 @@
zmq_msg_get(3)
==============
NAME
----
zmq_msg_get - get message property
SYNOPSIS
--------
*int zmq_msg_get (zmq_msg_t '*message', int 'property');*
DESCRIPTION
-----------
The _zmq_msg_get()_ function shall return the value for the property
specified by the 'property' argument for the message pointed to by the
'message' argument.
The following properties can be retrieved with the _zmq_msg_get()_ function:
*ZMQ_MORE*::
Indicates that there are more message frames to follow after the 'message'.
*ZMQ_SRCFD*::
Returns the file descriptor of the socket the 'message' was read from. This
allows application to retrieve the remote endpoint via 'getpeername(2)'. Be
aware that the respective socket might be closed already, reused even.
Currently only implemented for TCP sockets.
*ZMQ_SHARED*::
Indicates that a message MAY share underlying storage with another copy of
this message.
RETURN VALUE
------------
The _zmq_msg_get()_ function shall return the value for the property if
successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EINVAL*::
The requested _property_ is unknown.
EXAMPLE
-------
.Receiving a multi-frame message
----
zmq_msg_t frame;
while (true) {
// Create an empty 0MQ message to hold the message frame
int rc = zmq_msg_init (&frame);
assert (rc == 0);
// Block until a message is available to be received from socket
rc = zmq_msg_recv (socket, &frame, 0);
assert (rc != -1);
if (zmq_msg_get (&frame, ZMQ_MORE))
fprintf (stderr, "more\n");
else {
fprintf (stderr, "end\n");
break;
}
zmq_msg_close (&frame);
}
----
SEE ALSO
--------
linkzmq:zmq_msg_set[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

83
vendor/ZMQ/doc/zmq_msg_gets.txt vendored Normal file
View File

@@ -0,0 +1,83 @@
zmq_msg_gets(3)
===============
NAME
----
zmq_msg_gets - get message metadata property
SYNOPSIS
--------
*const char *zmq_msg_gets (zmq_msg_t '*message', const char *'property');*
DESCRIPTION
-----------
The _zmq_msg_gets()_ function shall return the string value for the metadata
property specified by the 'property' argument for the message pointed to by
the 'message' argument. Both the 'property' argument and the 'value'
shall be NULL-terminated UTF8-encoded strings.
Metadata is defined on a per-connection basis during the ZeroMQ connection
handshake as specified in <rfc.zeromq.org/spec:37>. Applications can set
metadata properties using linkzmq:zmq_setsockopt[3] option ZMQ_METADATA.
Application metadata properties must be prefixed with 'X-'.
In addition to application metadata, the following ZMTP properties can be
retrieved with the _zmq_msg_gets()_ function:
Socket-Type
Routing-Id
Note: 'Identity' is a deprecated alias for 'Routing-Id'.
Additionally, when available for the underlying transport, the *Peer-Address*
property will return the IP address of the remote endpoint as returned by
getnameinfo(2).
The names of these properties are also defined in _zmq.h_ as
_ZMQ_MSG_PROPERTY_SOCKET_TYPE_ _ZMQ_MSG_PROPERTY_ROUTING_ID_, and
_ZMQ_MSG_PROPERTY_PEER_ADDRESS_.
Currently, these definitions are only available as a DRAFT API.
Other properties may be defined based on the underlying security mechanism,
see ZAP authenticated connection sample below.
RETURN VALUE
------------
The _zmq_msg_gets()_ function shall return the string value for the property
if successful. Otherwise it shall return NULL and set 'errno' to one of the
values defined below. The caller shall not modify or free the returned value,
which shall be owned by the message. The encoding of the property and value
shall be UTF8.
ERRORS
------
*EINVAL*::
The requested _property_ is unknown.
EXAMPLE
-------
.Getting the ZAP authenticated user id for a message:
----
zmq_msg_t msg;
zmq_msg_init (&msg);
rc = zmq_msg_recv (&msg, dealer, 0);
assert (rc != -1);
const char *user_id = zmq_msg_gets (&msg, ZMQ_MSG_PROPERTY_USER_ID);
zmq_msg_close (&msg);
----
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_setsockopt[3]
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>.

65
vendor/ZMQ/doc/zmq_msg_init.txt vendored Normal file
View File

@@ -0,0 +1,65 @@
zmq_msg_init(3)
===============
NAME
----
zmq_msg_init - initialise empty 0MQ message
SYNOPSIS
--------
*int zmq_msg_init (zmq_msg_t '*msg');*
DESCRIPTION
-----------
The _zmq_msg_init()_ function shall initialise the message object referenced by
'msg' to represent an empty message. This function is most useful when called
before receiving a message with _zmq_msg_recv()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.
RETURN VALUE
------------
The _zmq_msg_init()_ function always returns zero.
ERRORS
------
No errors are defined.
EXAMPLE
-------
.Receiving a message from a socket
----
zmq_msg_t msg;
rc = zmq_msg_init (&msg);
assert (rc == 0);
int nbytes = zmq_msg_recv (socket, &msg, 0);
assert (nbytes != -1);
----
SEE ALSO
--------
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
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>.

59
vendor/ZMQ/doc/zmq_msg_init_buffer.txt vendored Normal file
View File

@@ -0,0 +1,59 @@
zmq_msg_init_buffer(3)
======================
NAME
----
zmq_msg_init_buffer - initialise 0MQ message with buffer copy
SYNOPSIS
--------
*int zmq_msg_init_buffer (zmq_msg_t '*msg', const void '*buf', size_t 'size');*
DESCRIPTION
-----------
The _zmq_msg_init_buffer()_ function shall allocate any resources required to
store a message 'size' bytes long and initialise the message object referenced
by 'msg' to represent a copy of the buffer referenced by the 'buf' and
'size' arguments.
The implementation shall choose whether to store message content on the stack
(small messages) or on the heap (large messages).
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_buffer()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.
RETURN VALUE
------------
The _zmq_msg_init_buffer()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOMEM*::
Insufficient storage space is available.
SEE ALSO
--------
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
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>.

90
vendor/ZMQ/doc/zmq_msg_init_data.txt vendored Normal file
View File

@@ -0,0 +1,90 @@
zmq_msg_init_data(3)
====================
NAME
----
zmq_msg_init_data - initialise 0MQ message from a supplied buffer
SYNOPSIS
--------
*typedef void (zmq_free_fn) (void '*data', void '*hint');*
*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
DESCRIPTION
-----------
The _zmq_msg_init_data()_ function shall initialise the message object
referenced by 'msg' to represent the content referenced by the buffer located
at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
0MQ shall take ownership of the supplied buffer.
If provided, the deallocation function 'ffn' shall be called once the data
buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments
supplied to _zmq_msg_init_data()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
CAUTION: The deallocation function 'ffn' needs to be thread-safe, since it
will be called from an arbitrary thread.
CAUTION: If the deallocation function is not provided, the allocated memory
will not be freed, and this may cause a memory leak.
CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.
RETURN VALUE
------------
The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOMEM*::
Insufficient storage space is available.
EXAMPLE
-------
.Initialising a message from a supplied buffer
----
void my_free (void *data, void *hint)
{
free (data);
}
/* ... */
void *data = malloc (6);
assert (data);
memcpy (data, "ABCDEF", 6);
zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
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>.

59
vendor/ZMQ/doc/zmq_msg_init_size.txt vendored Normal file
View File

@@ -0,0 +1,59 @@
zmq_msg_init_size(3)
====================
NAME
----
zmq_msg_init_size - initialise 0MQ message of a specified size
SYNOPSIS
--------
*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
DESCRIPTION
-----------
The _zmq_msg_init_size()_ function shall allocate any resources required to
store a message 'size' bytes long and initialise the message object referenced
by 'msg' to represent the newly allocated message.
The implementation shall choose whether to store message content on the stack
(small messages) or on the heap (large messages). For performance reasons
_zmq_msg_init_size()_ shall not clear the message data.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.
RETURN VALUE
------------
The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*ENOMEM*::
Insufficient storage space is available.
SEE ALSO
--------
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
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>.

65
vendor/ZMQ/doc/zmq_msg_more.txt vendored Normal file
View File

@@ -0,0 +1,65 @@
zmq_msg_more(3)
===============
NAME
----
zmq_msg_more - indicate if there are more message parts to receive
SYNOPSIS
--------
*int zmq_msg_more (zmq_msg_t '*message');*
DESCRIPTION
-----------
The _zmq_msg_more()_ function indicates whether this is part of a multi-part
message, and there are further parts to receive. This method can safely be
called after _zmq_msg_close()_. This method is identical to _zmq_msg_get()_
with an argument of ZMQ_MORE.
RETURN VALUE
------------
The _zmq_msg_more()_ function shall return zero if this is the final part of
a multi-part message, or the only part of a single-part message. It shall
return 1 if there are further parts to receive.
EXAMPLE
-------
.Receiving a multi-part message
----
zmq_msg_t part;
while (true) {
// Create an empty 0MQ message to hold the message part
int rc = zmq_msg_init (&part);
assert (rc == 0);
// Block until a message is available to be received from socket
rc = zmq_msg_recv (socket, &part, 0);
assert (rc != -1);
if (zmq_msg_more (&part))
fprintf (stderr, "more\n");
else {
fprintf (stderr, "end\n");
break;
}
zmq_msg_close (&part);
}
----
SEE ALSO
--------
linkzmq:zmq_msg_get[3]
linkzmq:zmq_msg_set[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

53
vendor/ZMQ/doc/zmq_msg_move.txt vendored Normal file
View File

@@ -0,0 +1,53 @@
zmq_msg_move(3)
===============
NAME
----
zmq_msg_move - move content of a message to another message
SYNOPSIS
--------
*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION
-----------
The _zmq_msg_move()_ function shall move the content of the message object
referenced by 'src' to the message object referenced by 'dest'. No actual
copying of message content is performed, 'dest' is simply updated to reference
the new content. 'src' becomes an empty message after calling _zmq_msg_move()_.
The original content of 'dest', if any, shall be released.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
Invalid message.
SEE ALSO
--------
linkzmq:zmq_msg_copy[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

128
vendor/ZMQ/doc/zmq_msg_recv.txt vendored Normal file
View File

@@ -0,0 +1,128 @@
zmq_msg_recv(3)
===============
NAME
----
zmq_msg_recv - receive a message part from a socket
SYNOPSIS
--------
*int zmq_msg_recv (zmq_msg_t '*msg', void '*socket', int 'flags');*
DESCRIPTION
-----------
The _zmq_msg_recv()_ function is identical to linkzmq:zmq_recvmsg[3], which
shall be deprecated in future versions. _zmq_msg_recv()_ is more consistent
with other message manipulation functions.
The _zmq_msg_recv()_ function shall receive a message part from the socket
referenced by the 'socket' argument and store it in the message referenced by
the 'msg' argument. Any content previously stored in 'msg' shall be properly
deallocated. If there are no message parts available on the specified 'socket'
the _zmq_msg_recv()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below:
*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_msg_recv()_
function shall fail with 'errno' set to EAGAIN.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that processes multi-part messages must use the _ZMQ_RCVMORE_
linkzmq:zmq_getsockopt[3] option after calling _zmq_msg_recv()_ to determine if
there are further parts to receive.
RETURN VALUE
------------
The _zmq_msg_recv()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_msg_recv()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_msg_recv()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before a message was
available.
*EFAULT*::
The message passed to the function was invalid.
EXAMPLE
-------
.Receiving a message from a socket
----
/* Create an empty 0MQ message */
zmq_msg_t msg;
int rc = zmq_msg_init (&msg);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_msg_recv (&msg, socket, 0);
assert (rc != -1);
/* Release message */
zmq_msg_close (&msg);
----
.Receiving a multi-part message
----
int more;
size_t more_size = sizeof (more);
do {
/* Create an empty 0MQ message to hold the message part */
zmq_msg_t part;
int rc = zmq_msg_init (&part);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_msg_recv (&part, socket, 0);
assert (rc != -1);
/* Determine if more message parts are to follow */
rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
assert (rc == 0);
zmq_msg_close (&part);
} while (more);
----
SEE ALSO
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_msg_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

61
vendor/ZMQ/doc/zmq_msg_routing_id.txt vendored Normal file
View File

@@ -0,0 +1,61 @@
zmq_msg_routing_id(3)
=====================
NAME
----
zmq_msg_routing_id - return routing ID for message, if any
SYNOPSIS
--------
*uint32_t zmq_msg_routing_id (zmq_msg_t '*message');*
DESCRIPTION
-----------
The _zmq_msg_routing_id()_ function returns the routing ID for the message,
if any. The routing ID is set on all messages received from a 'ZMQ_SERVER'
socket. To send a message to a 'ZMQ_SERVER' socket you must set the routing
ID of a connected 'ZMQ_CLIENT' peer. Routing IDs are transient.
RETURN VALUE
------------
The _zmq_msg_routing_id()_ function shall return zero if there is no routing
ID, otherwise it shall return an unsigned 32-bit integer greater than zero.
EXAMPLE
-------
.Receiving a client message and routing ID
----
void *ctx = zmq_ctx_new ();
assert (ctx);
void *server = zmq_socket (ctx, ZMQ_SERVER);
assert (server);
int rc = zmq_bind (server, "tcp://127.0.0.1:8080");
assert (rc == 0);
zmq_msg_t message;
rc = zmq_msg_init (&message);
assert (rc == 0);
// Receive a message from socket
rc = zmq_msg_recv (server, &message, 0);
assert (rc != -1);
uint32_t routing_id = zmq_msg_routing_id (&message);
assert (routing_id);
----
SEE ALSO
--------
linkzmq:zmq_msg_set_routing_id[3]
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>.

132
vendor/ZMQ/doc/zmq_msg_send.txt vendored Normal file
View File

@@ -0,0 +1,132 @@
zmq_msg_send(3)
===============
NAME
----
zmq_msg_send - send a message part on a socket
SYNOPSIS
--------
*int zmq_msg_send (zmq_msg_t '*msg', void '*socket', int 'flags');*
DESCRIPTION
-----------
The _zmq_msg_send()_ function is identical to linkzmq:zmq_sendmsg[3], which
shall be deprecated in future versions. _zmq_msg_send()_ is more consistent
with other message manipulation functions.
The _zmq_msg_send()_ function shall queue the message referenced by the 'msg'
argument to be sent to the socket referenced by the 'socket' argument. The
'flags' argument is a combination of the flags defined below:
*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_msg_send()_ function shall fail with 'errno' set
to EAGAIN.
*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.
The _zmq_msg_t_ structure passed to _zmq_msg_send()_ is nullified on a
successful call. If you want to send the same message to multiple sockets you
have to copy it (e.g. using _zmq_msg_copy()_). If the call fails, the
_zmq_msg_t_ structure stays intact, and must be consumed by another call to
_zmq_msg_send()_ on the same or another socket, or released using
_zmq_msg_close()_ to avoid a memory leak.
NOTE: A successful invocation of _zmq_msg_send()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message. You do not need
to call _zmq_msg_close()_ after a successful _zmq_msg_send()_.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.
RETURN VALUE
------------
The _zmq_msg_send()_ function shall return number of bytes in the message
if successful (if number of bytes is higher than 'MAX_INT', the function will
return 'MAX_INT'). Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_msg_send()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_msg_send()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before the message was
sent.
*EFAULT*::
Invalid message.
*EHOSTUNREACH*::
The message cannot be routed.
EXAMPLE
-------
.Filling in a message and sending it to a socket
----
/* Create a new message, allocating 6 bytes for message content */
zmq_msg_t msg;
int rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
/* Fill in message content with 'AAAAAA' */
memset (zmq_msg_data (&msg), 'A', 6);
/* Send the message to the socket */
rc = zmq_msg_send (&msg, socket, 0);
assert (rc == 6);
----
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_msg_send (&part1, socket, ZMQ_SNDMORE);
rc = zmq_msg_send (&part2, socket, ZMQ_SNDMORE);
/* Final part; no more parts to follow */
rc = zmq_msg_send (&part3, socket, 0);
----
SEE ALSO
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_msg_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

46
vendor/ZMQ/doc/zmq_msg_set.txt vendored Normal file
View File

@@ -0,0 +1,46 @@
zmq_msg_set(3)
==============
NAME
----
zmq_msg_set - set message property
SYNOPSIS
--------
*int zmq_msg_set (zmq_msg_t '*message', int 'property', int 'value');*
DESCRIPTION
-----------
The _zmq_msg_set()_ function shall set the property specified by the
'property' argument to the value of the 'value' argument for the 0MQ
message fragment pointed to by the 'message' argument.
Currently the _zmq_msg_set()_ function does not support any property names.
RETURN VALUE
------------
The _zmq_msg_set()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The requested property _property_ is unknown.
SEE ALSO
--------
linkzmq:zmq_msg_get[3]
linkzmq:zmq[7]
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>.

46
vendor/ZMQ/doc/zmq_msg_set_routing_id.txt vendored Normal file
View File

@@ -0,0 +1,46 @@
zmq_msg_set_routing_id(3)
=========================
NAME
----
zmq_msg_set_routing_id - set routing ID property on message
SYNOPSIS
--------
*int zmq_msg_set_routing_id (zmq_msg_t '*message', uint32_t 'routing_id');*
DESCRIPTION
-----------
The _zmq_msg_set_routing_id()_ function sets the 'routing_id' specified, on the
the message pointed to by the 'message' argument. The 'routing_id' must be
greater than zero. To get a valid routing ID, you must receive a message
from a 'ZMQ_SERVER' socket, and use the libzmq:zmq_msg_routing_id method.
Routing IDs are transient.
RETURN VALUE
------------
The _zmq_msg_set_routing_id()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The provided 'routing_id' is zero.
SEE ALSO
--------
linkzmq:zmq_msg_routing_id[3]
linkzmq:zmq[7]
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>.

49
vendor/ZMQ/doc/zmq_msg_size.txt vendored Normal file
View File

@@ -0,0 +1,49 @@
zmq_msg_size(3)
===============
NAME
----
zmq_msg_size - retrieve message content size in bytes
SYNOPSIS
--------
*size_t zmq_msg_size (zmq_msg_t '*msg');*
DESCRIPTION
-----------
The _zmq_msg_size()_ function shall return the size in bytes of the content of
the message object referenced by 'msg'.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
Upon successful completion, _zmq_msg_size()_ shall return the size of the
message content in bytes.
ERRORS
------
No errors are defined.
SEE ALSO
--------
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
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>.

27
vendor/ZMQ/doc/zmq_null.txt vendored Normal file
View File

@@ -0,0 +1,27 @@
zmq_null(7)
===========
NAME
----
zmq_null - no security or confidentiality
SYNOPSIS
--------
The NULL mechanism is defined by the ZMTP 3.0 specification:
<http://rfc.zeromq.org/spec:23>. This is the default security mechanism
for ZeroMQ sockets.
SEE ALSO
--------
linkzmq:zmq_plain[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]
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>.

188
vendor/ZMQ/doc/zmq_pgm.txt vendored Normal file
View File

@@ -0,0 +1,188 @@
zmq_pgm(7)
==========
NAME
----
zmq_pgm - 0MQ reliable multicast transport using PGM
SYNOPSIS
--------
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
transport of data over IP networks.
DESCRIPTION
-----------
0MQ implements two variants of PGM, the standard protocol where PGM datagrams
are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated
inside UDP datagrams (the 'epgm' transport).
The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
'ZMQ_SUB' socket types.
Further, PGM sockets are rate limited by default. For details, refer to the
'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
linkzmq:zmq_setsockopt[3].
CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
Additional privileges may be required on some operating systems for this
operation. Applications not requiring direct interoperability with other PGM
implementations are encouraged to use the 'epgm' transport instead which does
not require any special privileges.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the PGM transport, the transport is `pgm`, and for the EPGM protocol the
transport is `epgm`. The meaning of the 'address' part is defined below.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
followed by a semicolon, followed by a 'multicast address', followed by a colon
and a port number.
An 'interface' may be specified by either of the following:
* The interface name as defined by the operating system.
* The primary IPv4 address assigned to the interface, in its numeric
representation.
NOTE: Interface names are not standardised in any way and should be assumed to
be arbitrary and platform dependent. On Win32 platforms no short interface
names exist, thus only the primary IPv4 address may be used to specify an
'interface'. The 'interface' part can be omitted, in that case the default one
will be selected.
A 'multicast address' is specified by an IPv4 multicast address in its numeric
representation.
WIRE FORMAT
-----------
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
of data where 0MQ messages are not necessarily aligned with PGM datagram
boundaries and a single 0MQ message may span several PGM datagrams. This stream
of data consists of 0MQ messages encapsulated in 'frames' as described in
linkzmq:zmq_tcp[7].
PGM datagram payload
~~~~~~~~~~~~~~~~~~~~
The following ABNF grammar represents the payload of a single PGM datagram as
used by 0MQ:
....
datagram = (offset data)
offset = 2OCTET
data = *OCTET
....
In order for late joining consumers to be able to identify message boundaries,
each PGM datagram payload starts with a 16-bit unsigned integer in network byte
order specifying either the offset of the first message 'frame' in the datagram
or containing the value `0xFFFF` if the datagram contains solely an
intermediate part of a larger message.
Note that offset specifies where the first message begins rather than the first
message part. Thus, if there are trailing message parts at the beginning of
the packet the offset ignores them and points to first initial message part
in the packet.
The following diagram illustrates the layout of a single PGM datagram payload:
....
+------------------+----------------------+
| offset (16 bits) | data |
+------------------+----------------------+
....
The following diagram further illustrates how three example 0MQ frames are laid
out in consecutive PGM datagram payloads:
....
First datagram payload
+--------------+-------------+---------------------+
| Frame offset | Frame 1 | Frame 2, part 1 |
| 0x0000 | (Message 1) | (Message 2, part 1) |
+--------------+-------------+---------------------+
Second datagram payload
+--------------+---------------------+
| Frame offset | Frame 2, part 2 |
| 0xFFFF | (Message 2, part 2) |
+--------------+---------------------+
Third datagram payload
+--------------+----------------------------+-------------+
| Frame offset | Frame 2, final 8 bytes | Frame 3 |
| 0x0008 | (Message 2, final 8 bytes) | (Message 3) |
+--------------+----------------------------+-------------+
....
CONFIGURATION
-------------
The PGM is protocol is capable of multicasting data at high rates (500Mbps+)
with large messages (1MB+), however it requires setting the relevent ZMQ socket
options that are documented in linkzmq:zmq_setsockopt[3]:
* The 'ZMQ_RATE' should be set sufficiently high, e.g. 1Gbps
* The 'ZMQ_RCVBUF' should be increased on the subscriber, e.g. 4MB
* The 'ZMQ_SNDBUF' should be increased on the publisher, e.g. 4MB
It's important to note that the 'ZMQ_RCVBUF' and 'ZMQ_SNDBUF' options are
limited by the underlying host OS tx/rx buffer size limit. On linux, these can
be increased for the current session with the following commands:
....
# set tx/rx buffers to 4MB (default can also be read as the initial buffer size)
sudo sysctl -w net.core.rmem_max=4194304
sudo sysctl -w net.core.wmem_max=4194304
sudo sysctl -w net.core.rmem_default=4194304
sudo sysctl -w net.core.wmem_default=4194304
....
EXAMPLE
-------
.Connecting a socket
----
// Connecting to the multicast address 239.192.1.1, port 5555,
// using the first Ethernet network interface on Linux
// and the Encapsulated PGM protocol
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc == 0);
// Connecting to the multicast address 239.192.1.1, port 5555,
// using the network interface with the address 192.168.1.1
// and the standard PGM protocol
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]
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>.

37
vendor/ZMQ/doc/zmq_plain.txt vendored Normal file
View File

@@ -0,0 +1,37 @@
zmq_plain(7)
============
NAME
----
zmq_plain - clear-text authentication
SYNOPSIS
--------
The PLAIN mechanism defines a simple username/password mechanism that
lets a server authenticate a client. PLAIN makes no attempt at security
or confidentiality. It is intended for use on internal networks where
security requirements are low. The PLAIN mechanism is defined by this
document: <http://rfc.zeromq.org/spec:24>.
USAGE
-----
To use PLAIN, the server shall set the ZMQ_PLAIN_SERVER option, and the
client shall set the ZMQ_PLAIN_USERNAME and ZMQ_PLAIN_PASSWORD socket
options. Which peer binds, and which connects, is not relevant.
SEE ALSO
--------
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]
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>.

145
vendor/ZMQ/doc/zmq_poll.txt vendored Normal file
View File

@@ -0,0 +1,145 @@
zmq_poll(3)
===========
NAME
----
zmq_poll - input/output multiplexing
SYNOPSIS
--------
*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
DESCRIPTION
-----------
The _zmq_poll()_ function provides a mechanism for applications to multiplex
input/output events in a level-triggered fashion over a set of sockets. Each
member of the array pointed to by the 'items' argument is a *zmq_pollitem_t*
structure. The 'nitems' argument specifies the number of items in the 'items'
array. The *zmq_pollitem_t* structure is defined as follows:
["literal", subs="quotes"]
typedef struct
{
void '*socket';
int 'fd';
short 'events';
short 'revents';
} zmq_pollitem_t;
For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
socket referenced by 'socket' *or* the standard socket specified by the file
descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
'socket' shall take precedence and the value of 'fd' shall be ignored.
For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
member, and then indicate any requested events that have occurred by setting the
bit corresponding to the event condition in the 'revents' member.
If none of the requested events have occurred on any *zmq_pollitem_t* item,
_zmq_poll()_ shall wait 'timeout' milliseconds for an event to occur on
any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
block indefinitely until a requested event has occurred on at least one
*zmq_pollitem_t*.
The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
by OR'ing a combination of the following event flags:
*ZMQ_POLLIN*::
For 0MQ sockets, at least one message may be received from the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
_poll()_ system call and generally means that at least one byte of data may be
read from 'fd' without blocking.
*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be sent to the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
_poll()_ system call and generally means that at least one byte of data may be
written to 'fd' without blocking.
*ZMQ_POLLERR*::
For standard sockets, this flag is passed through _zmq_poll()_ to the
underlying _poll()_ system call and generally means that some sort of error
condition is present on the socket specified by 'fd'. For 0MQ sockets this flag
has no effect if set in 'events', and shall never be returned in 'revents' by
_zmq_poll()_.
*ZMQ_POLLPRI*::
For 0MQ sockets this flags is of no use. For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more informations.
For file descriptor, refer to your use case: as an example, GPIO interrupts
are signaled through a POLLPRI event.
This flag has no effect on Windows.
NOTE: The _zmq_poll()_ function may be implemented or emulated using operating
system interfaces other than _poll()_, and as such may be subject to the limits
of those interfaces in ways not defined in this documentation.
THREAD SAFETY
-------------
The *zmq_pollitem_t* array must only be used by the thread which
will/is calling _zmq_poll_.
If a socket is contained in multiple *zmq_pollitem_t* arrays, each owned by a
different thread, the socket itself needs to be thead-safe (Server, Client, ...).
Otherwise, behaviour is undefined.
RETURN VALUE
------------
Upon successful completion, the _zmq_poll()_ function shall return the number
of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no
events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set
'errno' to one of the values defined below.
ERRORS
------
*ETERM*::
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was terminated.
*EFAULT*::
The provided 'items' was not valid (NULL).
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
EXAMPLE
-------
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
----
zmq_pollitem_t items [2];
/* First item refers to 0MQ socket 'socket' */
items[0].socket = socket;
items[0].events = ZMQ_POLLIN;
/* Second item refers to standard socket 'fd' */
items[1].socket = NULL;
items[1].fd = fd;
items[1].events = ZMQ_POLLIN;
/* Poll for events indefinitely */
int rc = zmq_poll (items, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in items[].revents */
----
SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
Your operating system documentation for the _poll()_ system call.
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>.

316
vendor/ZMQ/doc/zmq_poller.txt vendored Normal file
View File

@@ -0,0 +1,316 @@
zmq_poller(3)
===========
NAME
----
zmq_poller - input/output multiplexing
SYNOPSIS
--------
*void *zmq_poller_new (void);*
*int zmq_poller_destroy (void '*poller_p');*
*int zmq_poller_size (void '*poller');*
*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');*
*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');*
*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');*
*int zmq_poller_fd (void '*poller', zmq_fd_t '*fd');*
DESCRIPTION
-----------
The _zmq_poller_*_ functions provide a mechanism for applications to multiplex
input/output events in a level-triggered fashion over a set of sockets.
_zmq_poller_new_ and _zmq_poller_destroy_ manage the lifetime of a poller
instance. _zmq_poller_new_ creates and returns a new poller instance, while
_zmq_poller_destroy_ destroys it. A pointer to a valid poller must be passed
as the _poller_p_ argument of _zmq_poller_destroy_. In particular,
_zmq_poller_destroy_ may not be called multiple times for the same poller
instance. _zmq_poller_destroy_ sets the passed pointer to NULL in case of a
successful execution. _zmq_poller_destroy_ implicitly unregisters all
registered sockets and file descriptors.
_zmq_poller_size_ queries the number of sockets or file descriptors registered
with a poller. The initial size of a poller is 0, a successful add operation
increases the size by 1 and a successful remove operation decreases the size
by 1. The size is unaffected by the events specified.
_zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_ manage the 0MQ
sockets registered with a poller.
_zmq_poller_add_ registers a new _socket_ with a given _poller_. Both _poller_
and _socket_ must point to valid 0MQ objects. The _events_ parameter specifies
which event types the client wants to subscribe to. It is legal to specify no
events (i.e. 0), and activate them later with _zmq_poller_modify_.
In addition, _user_data_ may be specified, which is not used by the poller, but
passed back to the caller when an event was signalled in a call to
_zmq_poller_wait_ or _zmq_poller_wait_all_. _user_data_ may be NULL. If it is
not NULL, it must be a valid pointer. Otherwise, behaviour is undefined.
You must only add a socket to a single poller instance once (unless
_zmq_poller_remove_ has been called for that socket before). You may
add a socket to multiple poller instances, if the socket itself
is explicitly thread-safe (Server, Client, ...). If the socket is not,
you may invoke undefined behavior.
_zmq_poller_modify_ modifies the subscribed events for a socket. It is
legal to specify no events (i.e. 0) to disable events temporarily, and
reactivate them later with another call to _zmq_poller_modify_.
_zmq_poller_remove_ removes a socket registration completely.
_zmq_poller_remove_ must be called before a socket is closed with _zmq_close_.
Note that it is not necessary to call _zmq_poller_remove_ for any socket
before calling _zmq_poller_destroy_.
Also note that calling _zmq_poller_remove_ is not equivalent to calling
_zmq_poller_modify_ with no events. _zmq_poller_modify_ does not free resources
associated with the socket registration, and requires that the _socket_
remains valid.
_zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_ are
analogous to the previous functions but manage regular file descriptiors
registered with a poller. On Windows, these functions can only be used with
WinSock sockets.
In the following, 0MQ sockets added with _zmq_poller_add_ and file descriptors
added with _zmq_poller_add_fd_ are referred to as 'registered objects'.
The *zmq_poller_event_t* structure is defined as follows:
["literal", subs="quotes"]
typedef struct
{
void *socket;
zmq_fd_t fd;
void *user_data;
short events;
} zmq_poller_event_t;
For each registered object, _zmq_poller_wait_all()_ shall examine the
registered objects for the event(s) currently registered.
If none of the registered events have occurred, _zmq_poller_wait_all_ shall
wait 'timeout' milliseconds for an event to occur on any of the registered
objects. If the value of 'timeout' is `0`, _zmq_poller_wait_all_ shall
return immediately. If the value of 'timeout' is `-1`, _zmq_poller_wait_all_
shall block indefinitely until one event has occurred on any of the
registered objects.
The 'events' argument _zmq_poller_wait_all_ must be a pointer to an array of
at least 'n_events' elements. Behaviour is undefined if 'events' does not point
to an array of at least 'n_events' elements.
_zmq_poller_wait_all_ returns at most 'n_events' events. If more than
'n_events' events were signalled, only an unspecified subset of the signalled
events is returned through 'events'.
A caller is advised to ensure that 'n_events' is equal to the number of
registered objects. Otherwise, a livelock situation may result: If more than
'n_events' registered objects have an active event on each call to
_zmq_poller_wait_all_, it might happen that the same subset of registered
objects is always returned, and the caller never notices the events on the
others. The number of objects registered can be queried with
_zmq_poller_size_.
_zmq_poller_wait_all_ returns the number of valid elements. The valid elements
are placed in positions '0' to 'n_events - 1' in the 'events' array. All
members of a valid element are set to valid values by _zmq_poller_wait_all_.
For socket events 'socket' is non-null and 'fd' is an operating system
specific value for an invalid socket (-1 or INVALID_SOCKET). For fd events
'socket' is NULL and 'fd' is a valid file descriptor.
The client does therefore not need to initialize the contents of the events
array before a call to _zmq_poller_wait_all_. It is unspecified whether the
the remaining elements of 'events' are written to by _zmq_poller_wait_all_.
_zmq_poller_fd_ queries the file descriptor associated with the zmq_poller,
and stores it in the address pointer to by 'fd'.
The zmq_poller is only guaranteed to have a file descriptor if
at least one thread-safe socket is currently registered.
Note that closing a socket that is registered in a poller leads to undefined
behavior. The socket must be unregistered first.
EVENT TYPES
-----------
The 'events' parameter of _zmq_poller_add_ and _zmq_poller_modify_, and the
'events' member of the zmq_poller_event_t structure are bit masks constructed
by OR'ing a combination of the following event flags:
*ZMQ_POLLIN*::
For 0MQ sockets, at least one message may be received from the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
_poll()_ system call and generally means that at least one byte of data may be
read from 'fd' without blocking.
*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be sent to the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
_poll()_ system call and generally means that at least one byte of data may be
written to 'fd' without blocking.
*ZMQ_POLLERR*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets, this flag is passed through _zmq_poller_wait_all_ to the
underlying _poll()_ system call and generally means that some sort of error
condition is present on the socket specified by 'fd'.
*ZMQ_POLLPRI*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more informations.
For a file descriptor, refer to your OS documentation: as an example, GPIO
interrupts are signaled through a POLLPRI event.
This flag has no effect on Windows.
NOTE: The _zmq_poller_*_ functions may be implemented or emulated using operating
system interfaces other than _poll()_, and as such may be subject to the limits
of those interfaces in ways not defined in this documentation.
THREAD SAFETY
-------------
Like most other 0MQ objects, a poller is not thread-safe. All operations must
be called from the same thread. Otherwise, behaviour is undefined.
In addition to that, if you want to add a socket to multiple existing poller
instances, the socket itself needs to be thread-safe (Server, Client, ...).
Otherwise, behaviour is undefined.
RETURN VALUE
------------
_zmq_poller_new_ returns a valid pointer to a poller, or NULL in case of a failure.
All functions that return an int, return -1 in case of a failure. In that case,
zmq_errno() can be used to query the type of the error as described below.
_zmq_poller_wait_all_ returns the number of events signalled and returned in
the events array. It never returns 0.
All other functions return 0 in case of a successful execution.
ERRORS
------
On _zmq_poller_new_:
*ENOMEM*::
A new poller could not be allocated successfully.
On _zmq_poller_destroy_:
*EFAULT*::
_poller_p_ did not point to a valid poller. Note that passing an invalid pointer (e.g.
pointer to deallocated memory) may cause undefined behaviour (e.g. an access violation).
On _zmq_poller_size_:
*EFAULT*::
_poller_ did not point to a valid poller. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
On _zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_:
*EFAULT*::
_poller_ did not point to a valid poller. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
*ENOTSOCK*::
_socket_ did not point to a valid socket. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
On _zmq_poller_add_:
*EMFILE*::
TODO
On _zmq_poller_add_ or _zmq_poller_add_fd_:
*ENOMEM*::
Necessary resources could not be allocated.
*EINVAL*::
_socket_ resp. _fd_ was already registered with the poller.
On _zmq_poller_modify_, _zmq_poller_modify_fd_, _zmq_poller_remove_ or
_zmq_poller_remove_fd_:
*EINVAL*::
_socket_ resp. _fd_ was not registered with the poller.
On _zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_:
*EBADF**:
The _fd_ specified was the retired fd.
On _zmq_poller_wait_ and _zmq_poller_wait_all_:
*ENOMEM*::
Necessary resources could not be allocated.
*ETERM*::
At least one of the registered objects is a 'socket' whose associated 0MQ
'context' was terminated.
*EFAULT*::
The provided 'events' was NULL, or 'poller' did not point to a valid poller,
or there are no registered objects or all event subscriptions are disabled
and 'timeout' was negative.
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
*EAGAIN*::
No registered event was signalled before the timeout was reached.
On _zmq_poller_fd_:
*EINVAL*::
The poller has no associated file descriptor.
*EFAULT*::
The provided 'poller' did not point to a valid poller.
EXAMPLE
-------
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
----
void *poller = zmq_poller_new ();
zmq_poller_event_t events [2];
/* First item refers to 0MQ socket 'socket' */
zmq_poller_add (poller, socket, NULL, ZMQ_POLLIN);
/* Second item refers to standard socket 'fd' */
zmq_poller_add_fd (poller, fd, NULL, ZMQ_POLLIN);
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (poller, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
zmq_poller_destroy (poller);
----
SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
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>.

99
vendor/ZMQ/doc/zmq_proxy.txt vendored Normal file
View File

@@ -0,0 +1,99 @@
zmq_proxy(3)
============
NAME
----
zmq_proxy - start built-in 0MQ proxy
SYNOPSIS
--------
*int zmq_proxy (void '*frontend', void '*backend', void '*capture');*
DESCRIPTION
-----------
The _zmq_proxy()_ function starts the built-in 0MQ proxy in the current
application thread.
The proxy 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. The direction is conceptual only; the proxy is fully
symmetric and there is no technical difference between frontend and backend.
Before calling _zmq_proxy()_ you must set any socket options, and connect or
bind both frontend and backend sockets. The two conventional proxy models are:
_zmq_proxy()_ runs in the current thread and returns only if/when the current
context is closed.
If the capture socket is not NULL, the proxy shall send all messages, received
on both frontend and backend, to the capture socket. The capture socket should
be a 'ZMQ_PUB', 'ZMQ_DEALER', 'ZMQ_PUSH', or 'ZMQ_PAIR' socket.
Refer to linkzmq:zmq_socket[3] for a description of the available socket types.
EXAMPLE USAGE
-------------
Shared Queue
~~~~~~~~~~~~
When the frontend is a ZMQ_ROUTER socket, and the backend is a ZMQ_DEALER
socket, the proxy shall act as a shared queue that collects requests from a
set of clients, and distributes these fairly among a set of services.
Requests shall be fair-queued from frontend connections and distributed evenly
across backend connections. Replies shall automatically return to the client
that made the original request.
Forwarder
~~~~~~~~~
When the frontend is a ZMQ_XSUB socket, and the backend is a ZMQ_XPUB socket,
the proxy shall act as a message forwarder that collects messages from a set
of publishers and forwards these to a set of subscribers. This may be used to
bridge networks transports, e.g. read on tcp:// and forward on pgm://.
Streamer
~~~~~~~~
When the frontend is a ZMQ_PULL socket, and the backend is a ZMQ_PUSH socket,
the proxy shall collect tasks from a set of clients and forwards these to a set
of workers using the pipeline pattern.
RETURN VALUE
------------
The _zmq_proxy()_ function always returns `-1` and 'errno' set to *ETERM* or
*EINTR* (the 0MQ 'context' associated with either of the specified sockets was
terminated) or *EFAULT* (the provided 'frontend' or 'backend' was invalid).
EXAMPLE
-------
.Creating a shared queue proxy
----
// Create frontend and backend sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (frontend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (backend);
// Bind both sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
// Start the queue proxy, which runs until ETERM
zmq_proxy (frontend, backend, NULL);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

126
vendor/ZMQ/doc/zmq_proxy_steerable.txt vendored Normal file
View File

@@ -0,0 +1,126 @@
zmq_proxy_steerable(3)
======================
NAME
----
zmq_proxy_steerable - built-in 0MQ proxy with control flow
SYNOPSIS
--------
*int zmq_proxy_steerable (const void '*frontend', const void '*backend',
const void '*capture', const void '*control');*
DESCRIPTION
-----------
The _zmq_proxy_steerable()_ function starts the built-in 0MQ proxy in the
current application thread, as _zmq_proxy()_ do. Please, refer to this function
for the general description and usage. We describe here only the additional
control flow provided by the socket passed as the fourth argument "control".
If the control socket is not NULL, the proxy supports control flow. If
'PAUSE' is received on this socket, the proxy suspends its activities. If
'RESUME' is received, it goes on. If 'TERMINATE' is received, it terminates
smoothly. If 'STATISTICS' is received, the proxy will reply on the control socket
sending a multipart message with 8 frames, each with an unsigned integer 64-bit
wide that provide in the following order:
- number of messages received by the frontend socket
- number of bytes received by the frontend socket
- number of messages sent out the frontend socket
- number of bytes sent out the frontend socket
- number of messages received by the backend socket
- number of bytes received by the backend socket
- number of messages sent out the backend socket
- number of bytes sent out the backend socket
At start, the proxy runs normally as if zmq_proxy was used.
If the control socket is NULL, the function behave exactly as if linkzmq:zmq_proxy[3]
had been called.
Refer to linkzmq:zmq_socket[3] for a description of the available socket types.
Refer to linkzmq:zmq_proxy[3] for a description of the zmq_proxy.
EXAMPLE USAGE
-------------
cf zmq_proxy
RETURN VALUE
------------
The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is sent to its
control socket. Otherwise, it returns `-1` and 'errno' set to *ETERM* or
*EINTR* (the 0MQ 'context' associated with either of the specified sockets was
terminated) or *EFAULT* (the provided 'frontend' or 'backend' was invalid).
EXAMPLE
-------
.Creating a shared queue proxy
----
// Create frontend, backend and control sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (frontend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (backend);
void *control = zmq_socket (context, ZMQ_SUB);
assert (control);
// Bind sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
assert (zmq_connect (control, "tcp://*:5557") == 0);
// Subscribe to the control socket since we have chosen SUB here
assert (zmq_setsockopt (control, ZMQ_SUBSCRIBE, "", 0));
// Start the queue proxy, which runs until ETERM or "TERMINATE"
// received on the control socket
zmq_proxy_steerable (frontend, backend, NULL, control);
----
.Set up a controller in another node, process or whatever
----
void *control = zmq_socket (context, ZMQ_PUB);
assert (control);
assert (zmq_bind (control, "tcp://*:5557") == 0);
// pause the proxy
assert (zmq_send (control, "PAUSE", 5, 0) == 0);
// resume the proxy
assert (zmq_send (control, "RESUME", 6, 0) == 0);
// terminate the proxy
assert (zmq_send (control, "TERMINATE", 9, 0) == 0);
// check statistics
assert (zmq_send (control, "STATISTICS", 10, 0) == 0);
zmq_msg_t stats_msg;
while (1) {
assert (zmq_msg_init (&stats_msg) == 0);
assert (zmq_recvmsg (control, &stats_msg, 0) == sizeof (uint64_t));
assert (rc == sizeof (uint64_t));
printf ("Stat: %lu\n", *(unsigned long int *)zmq_msg_data (&stats_msg));
if (!zmq_msg_get (&stats_msg, ZMQ_MORE))
break;
assert (zmq_msg_close (&stats_msg) == 0);
}
assert (zmq_msg_close (&stats_msg) == 0);
---
SEE ALSO
--------
linkzmq:zmq_proxy[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

95
vendor/ZMQ/doc/zmq_recv.txt vendored Normal file
View File

@@ -0,0 +1,95 @@
zmq_recv(3)
===========
NAME
----
zmq_recv - receive a message part from a socket
SYNOPSIS
--------
*int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');*
DESCRIPTION
-----------
The _zmq_recv()_ function shall receive a message from the socket referenced
by the 'socket' argument and store it in the buffer referenced by the 'buf'
argument. Any bytes exceeding the length specified by the 'len' argument shall
be truncated. If there are no messages available on the specified 'socket'
the _zmq_recv()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below: The 'buf'
argument may be null if len is zero.
*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_recv()_
function shall fail with 'errno' set to EAGAIN.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that processes multi-part messages must use the _ZMQ_RCVMORE_
linkzmq:zmq_getsockopt[3] option after calling _zmq_recv()_ to determine if
there are further parts to receive.
RETURN VALUE
------------
The _zmq_recv()_ function shall return number of bytes in the message
if successful. Note that the value can exceed the value of the 'len' parameter
in case the message was truncated. If not successful the function shall return
`-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_recv()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_recv()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before a message was
available.
EXAMPLE
-------
.Receiving a message from a socket
----
char buf [256];
nbytes = zmq_recv (socket, buf, 256, 0);
assert (nbytes != -1);
----
SEE ALSO
--------
linkzmq:zmq_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

125
vendor/ZMQ/doc/zmq_recvmsg.txt vendored Normal file
View File

@@ -0,0 +1,125 @@
zmq_recvmsg(3)
==============
NAME
----
zmq_recvmsg - receive a message part from a socket
SYNOPSIS
--------
*int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION
-----------
The _zmq_recvmsg()_ function shall receive a message part from the socket
referenced by the 'socket' argument and store it in the message referenced by
the 'msg' argument. Any content previously stored in 'msg' shall be properly
deallocated. If there are no message parts available on the specified 'socket'
the _zmq_recvmsg()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below:
*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_recvmsg()_
function shall fail with 'errno' set to EAGAIN.
NOTE: this API method is deprecated in favor of zmq_msg_recv(3).
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that processes multi-part messages must use the _ZMQ_RCVMORE_
linkzmq:zmq_getsockopt[3] option after calling _zmq_recvmsg()_ to determine if
there are further parts to receive.
RETURN VALUE
------------
The _zmq_recvmsg()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_recvmsg()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_recvmsg()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before a message was
available.
*EFAULT*::
The message passed to the function was invalid.
EXAMPLE
-------
.Receiving a message from a socket
----
/* Create an empty 0MQ message */
zmq_msg_t msg;
int rc = zmq_msg_init (&msg);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_recvmsg (socket, &msg, 0);
assert (rc != -1);
/* Release message */
zmq_msg_close (&msg);
----
.Receiving a multi-part message
----
int more;
size_t more_size = sizeof (more);
do {
/* Create an empty 0MQ message to hold the message part */
zmq_msg_t part;
int rc = zmq_msg_init (&part);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_recvmsg (socket, &part, 0);
assert (rc != -1);
/* Determine if more message parts are to follow */
rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
assert (rc == 0);
zmq_msg_close (&part);
} while (more);
----
SEE ALSO
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

105
vendor/ZMQ/doc/zmq_send.txt vendored Normal file
View File

@@ -0,0 +1,105 @@
zmq_send(3)
===========
NAME
----
zmq_send - send a message part on a socket
SYNOPSIS
--------
*int zmq_send (void '*socket', const void '*buf', size_t 'len', int 'flags');*
DESCRIPTION
-----------
The _zmq_send()_ function shall queue a message created from the buffer
referenced by the 'buf' and 'len' arguments. The 'flags' argument is
a combination of the flags defined below:
*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_send()_ function shall fail with 'errno' set
to EAGAIN.
*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.
NOTE: A successful invocation of _zmq_send()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.
RETURN VALUE
------------
The _zmq_send()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_send()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_send()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before the message was
sent.
*EHOSTUNREACH*::
The message cannot be routed.
EXAMPLE
-------
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_send (socket, "ABC", 3, ZMQ_SNDMORE);
assert (rc == 3);
rc = zmq_send (socket, "DEFGH", 5, ZMQ_SNDMORE);
assert (rc == 5);
/* Final part; no more parts to follow */
rc = zmq_send (socket, "JK", 2, 0);
assert (rc == 2);
----
SEE ALSO
--------
linkzmq:zmq_send_const[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

104
vendor/ZMQ/doc/zmq_send_const.txt vendored Normal file
View File

@@ -0,0 +1,104 @@
zmq_send_const(3)
=================
NAME
----
zmq_send_const - send a constant-memory message part on a socket
SYNOPSIS
--------
*int zmq_send_const (void '*socket', const void '*buf', size_t 'len', int 'flags');*
DESCRIPTION
-----------
The _zmq_send_const()_ function shall queue a message created from the buffer
referenced by the 'buf' and 'len' arguments. The message buffer is assumed
to be constant-memory and will therefore not be copied or deallocated
in any way. The 'flags' argument is a combination of the flags defined below:
*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_send_const()_ function shall fail with 'errno' set
to EAGAIN.
*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.
NOTE: A successful invocation of _zmq_send_const()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.
RETURN VALUE
------------
The _zmq_send_const()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_send_const()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_send_const()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before the message was
sent.
*EHOSTUNREACH*::
The message cannot be routed.
EXAMPLE
-------
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_send_const (socket, "ABC", 3, ZMQ_SNDMORE);
assert (rc == 3);
rc = zmq_send_const (socket, "DEFGH", 5, ZMQ_SNDMORE);
assert (rc == 5);
/* Final part; no more parts to follow */
rc = zmq_send_const (socket, "JK", 2, 0);
assert (rc == 2);
----
SEE ALSO
--------
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

122
vendor/ZMQ/doc/zmq_sendmsg.txt vendored Normal file
View File

@@ -0,0 +1,122 @@
zmq_sendmsg(3)
==============
NAME
----
zmq_sendmsg - send a message part on a socket
SYNOPSIS
--------
*int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION
-----------
The _zmq_sendmsg()_ function shall queue the message referenced by the 'msg'
argument to be sent to the socket referenced by the 'socket' argument. The
'flags' argument is a combination of the flags defined below:
*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_sendmsg()_ function shall fail with 'errno' set
to EAGAIN.
*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.
The _zmq_msg_t_ structure passed to _zmq_sendmsg()_ is nullified during the
call. If you want to send the same message to multiple sockets you have to copy
it (e.g. using _zmq_msg_copy()_).
NOTE: A successful invocation of _zmq_sendmsg()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.
NOTE: this API method is deprecated in favor of zmq_msg_send(3).
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.
An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.
RETURN VALUE
------------
The _zmq_sendmsg()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.
ERRORS
------
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_sendmsg()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_sendmsg()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal before the message was
sent.
*EFAULT*::
Invalid message.
*EHOSTUNREACH*::
The message cannot be routed.
EXAMPLE
-------
.Filling in a message and sending it to a socket
----
/* Create a new message, allocating 6 bytes for message content */
zmq_msg_t msg;
int rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
/* Fill in message content with 'AAAAAA' */
memset (zmq_msg_data (&msg), 'A', 6);
/* Send the message to the socket */
rc = zmq_sendmsg (socket, &msg, 0);
assert (rc == 6);
----
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_sendmsg (socket, &part1, ZMQ_SNDMORE);
rc = zmq_sendmsg (socket, &part2, ZMQ_SNDMORE);
/* Final part; no more parts to follow */
rc = zmq_sendmsg (socket, &part3, 0);
----
SEE ALSO
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
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>.

1546
vendor/ZMQ/doc/zmq_setsockopt.txt vendored Normal file
View File

File diff suppressed because it is too large Load Diff

758
vendor/ZMQ/doc/zmq_socket.txt vendored Normal file
View File

@@ -0,0 +1,758 @@
zmq_socket(3)
=============
NAME
----
zmq_socket - create 0MQ socket
SYNOPSIS
--------
*void *zmq_socket (void '*context', int 'type');*
DESCRIPTION
-----------
The 'zmq_socket()' function shall create a 0MQ socket within the specified
'context' and return an opaque handle to the newly created socket. The 'type'
argument specifies the socket type, which determines the semantics of
communication over the socket.
The newly created socket is initially unbound, and not associated with any
endpoints. In order to establish a message flow a socket must first be
connected to at least one endpoint with linkzmq:zmq_connect[3], or at least one
endpoint must be created for accepting incoming connections with
linkzmq:zmq_bind[3].
.Key differences to conventional sockets
Generally speaking, conventional sockets present a _synchronous_ interface to
either connection-oriented reliable byte streams (SOCK_STREAM), or
connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets
present an abstraction of an asynchronous _message queue_, with the exact
queueing semantics depending on the socket type in use. Where conventional
sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer
discrete _messages_.
0MQ sockets being _asynchronous_ means that the timings of the physical
connection setup and tear down, reconnect and effective delivery are transparent
to the user and organized by 0MQ itself. Further, messages may be _queued_ in
the event that a peer is unavailable to receive them.
Conventional sockets allow only strict one-to-one (two peers), many-to-one
(many clients, one server), or in some cases one-to-many (multicast)
relationships. With the exception of 'ZMQ_PAIR' and 'ZMQ_CHANNEL', 0MQ sockets may be connected
*to multiple endpoints* using _zmq_connect()_, while simultaneously accepting
incoming connections *from multiple endpoints* bound to the socket using
_zmq_bind()_, thus allowing many-to-many relationships.
.Thread safety
0MQ has both thread safe socket type and _not_ thread safe socket types.
Applications MUST NOT use a _not_ thread safe socket
from multiple threads under any circumstances. Doing so results in undefined
behaviour.
Following are the thread safe sockets:
* ZMQ_CLIENT
* ZMQ_SERVER
* ZMQ_DISH
* ZMQ_RADIO
* ZMQ_SCATTER
* ZMQ_GATHER
* ZMQ_PEER
* ZMQ_CHANNEL
.Socket types
The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ which is built from related socket types.
Client-server pattern
~~~~~~~~~~~~~~~~~~~~~
The client-server pattern is used to allow a single 'ZMQ_SERVER' _server_ talk
to one or more 'ZMQ_CLIENT' _clients_. The client always starts the conversation,
after which either peer can send messages asynchronously, to the other.
The client-server pattern is formally defined by http://rfc.zeromq.org/spec:41.
NOTE: Server-client is still in draft phase.
ZMQ_CLIENT
^^^^^^^^^^
A 'ZMQ_CLIENT' socket talks to a 'ZMQ_SERVER' socket. Either peer can connect,
though the usual and recommended model is to bind the 'ZMQ_SERVER' and connect
the 'ZMQ_CLIENT'.
If the 'ZMQ_CLIENT' socket has established a connection, linkzmq:zmq_send[3]
will accept messages, queue them, and send them as rapidly as the network
allows. The outgoing buffer limit is defined by the high water mark for the
socket. If the outgoing buffer is full, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer,
linkzmq:zmq_send[3] will block.
The 'ZMQ_CLIENT' socket will not drop messages.
When a 'ZMQ_CLIENT' socket is connected to multiple 'ZMQ_SERVER' sockets,
outgoing messages are distributed between connected peers on a round-robin
basis. Likewise, the 'ZMQ_CLIENT' socket receives messages fairly from each
connected peer. This usage is sensible only for stateless protocols.
'ZMQ_CLIENT' sockets are threadsafe and can be used from multiple threads
at the same time. Note that replies from a 'ZMQ_SERVER' socket will go to
the first client thread that calls linkzmq:zmq_msg_recv[3]. If you need to get
replies back to the originating thread, use one 'ZMQ_CLIENT' socket per
thread.
NOTE: 'ZMQ_CLIENT' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.
[horizontal]
.Summary of ZMQ_CLIENT characteristics
Compatible peer sockets:: 'ZMQ_SERVER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Fair-queued
Action in mute state:: Block
ZMQ_SERVER
^^^^^^^^^^
A 'ZMQ_SERVER' socket talks to a set of 'ZMQ_CLIENT' sockets. A 'ZMQ_SERVER'
socket can only reply to an incoming message: the 'ZMQ_CLIENT' peer must
always initiate a conversation.
Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with linkzmq:zmq_msg_routing_id[3]. To send
a message to a given 'ZMQ_CLIENT' peer the application must set the peer's
'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3].
If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the client peer is full, the send call shall block, unless ZMQ_DONTWAIT is
used in the send, in which case it shall fail with EAGAIN. The 'ZMQ_SERVER'
socket shall not drop messages in any case.
NOTE: 'ZMQ_SERVER' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.
[horizontal]
.Summary of ZMQ_SERVER characteristics
Compatible peer sockets:: 'ZMQ_CLIENT'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Return EAGAIN
Radio-dish pattern
~~~~~~~~~~~~~~~~~~
The radio-dish pattern is used for one-to-many distribution of data from
a single _publisher_ to multiple _subscribers_ in a fan out fashion.
Radio-dish is using groups (vs Pub-sub topics), Dish sockets can join a group
and each message sent by Radio sockets belong to a group.
Groups are null terminated strings limited to 16 chars length (including null).
The intention is to increase the length to 40 chars (including null).
The encoding of groups shall be UTF8.
Groups are matched using exact matching (vs prefix matching of PubSub).
NOTE: Radio-dish is still in draft phase.
ZMQ_RADIO
^^^^^^^
A socket of type 'ZMQ_RADIO' is used by a _publisher_ to distribute data.
Each message belong to a group, a group is specified with linkzmq:zmq_msg_set_group[3].
Messages are distributed to all members of a group.
The linkzmq:zmq_recv[3] function is not implemented for this socket type.
When a 'ZMQ_RADIO' socket enters the 'mute' state due to having reached the
high water mark for a _subscriber_, then any messages that would be sent to the
_subscriber_ in question shall instead be dropped until the mute state
ends. The _zmq_send()_ function shall never block for this socket type.
NOTE: 'ZMQ_RADIO' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends. This limits them to single part data.
[horizontal]
.Summary of ZMQ_RADIO characteristics
Compatible peer sockets:: 'ZMQ_DISH'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop
ZMQ_DISH
^^^^^^^^
A socket of type 'ZMQ_DISH' is used by a _subscriber_ to subscribe to groups
distributed by a _radio_. Initially a 'ZMQ_DISH' socket is not subscribed to
any groups, use linkzmq:zmq_join[3] to
join a group.
To get the group the message belong to call linkzmq:zmq_msg_group[3].
The _zmq_send()_ function is not implemented for this socket type.
NOTE: 'ZMQ_DISH' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.
[horizontal]
.Summary of ZMQ_DISH characteristics
Compatible peer sockets:: 'ZMQ_RADIO'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Publish-subscribe pattern
~~~~~~~~~~~~~~~~~~~~~~~~~
The publish-subscribe pattern is used for one-to-many distribution of data from
a single _publisher_ to multiple _subscribers_ in a fan out fashion.
The publish-subscribe pattern is formally defined by http://rfc.zeromq.org/spec:29.
ZMQ_PUB
^^^^^^^
A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
Messages sent are distributed in a fan out fashion to all connected peers.
The linkzmq:zmq_recv[3] function is not implemented for this socket type.
When a 'ZMQ_PUB' socket enters the 'mute' state due to having reached the
high water mark for a _subscriber_, then any messages that would be sent to the
_subscriber_ in question shall instead be dropped until the mute state
ends. The _zmq_send()_ function shall never block for this socket type.
[horizontal]
.Summary of ZMQ_PUB characteristics
Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop
ZMQ_SUB
^^^^^^^
A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
any messages, use the 'ZMQ_SUBSCRIBE' option of linkzmq:zmq_setsockopt[3] to
specify which messages to subscribe to. The _zmq_send()_ function is not
implemented for this socket type.
[horizontal]
.Summary of ZMQ_SUB characteristics
Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
ZMQ_XPUB
^^^^^^^^
Same as ZMQ_PUB except that you can receive subscriptions from the peers
in form of incoming messages. Subscription message is a byte 1 (for
subscriptions) or byte 0 (for unsubscriptions) followed by the subscription
body. Messages without a sub/unsub prefix are also received, but have no
effect on subscription status.
[horizontal]
.Summary of ZMQ_XPUB characteristics
Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
Direction:: Unidirectional
Send/receive pattern:: Send messages, receive subscriptions
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop
ZMQ_XSUB
^^^^^^^^
Same as ZMQ_SUB except that you subscribe by sending subscription messages to
the socket. Subscription message is a byte 1 (for subscriptions) or byte 0
(for unsubscriptions) followed by the subscription body. Messages without a
sub/unsub prefix may also be sent, but have no effect on subscription status.
[horizontal]
.Summary of ZMQ_XSUB characteristics
Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
Direction:: Unidirectional
Send/receive pattern:: Receive messages, send subscriptions
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Drop
Pipeline pattern
~~~~~~~~~~~~~~~~
The pipeline pattern is used for distributing data to _nodes_ arranged in
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
is connected to at least one _node_. When a pipeline stage is connected to
multiple _nodes_ data is round-robined among all connected _nodes_.
The pipeline pattern is formally defined by http://rfc.zeromq.org/spec:30.
ZMQ_PUSH
^^^^^^^^
A socket of type 'ZMQ_PUSH' is used by a pipeline _node_ to send messages
to downstream pipeline _nodes_. Messages are round-robined to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.
When a 'ZMQ_PUSH' socket enters the 'mute' state due to having reached the
high water mark for all downstream _nodes_, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
then any linkzmq:zmq_send[3] operations on the socket shall block until the mute
state ends or at least one downstream _node_ becomes available for sending;
messages are not discarded.
[horizontal]
.Summary of ZMQ_PUSH characteristics
Compatible peer sockets:: 'ZMQ_PULL'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Round-robin
Action in mute state:: Block
ZMQ_PULL
^^^^^^^^
A socket of type 'ZMQ_PULL' is used by a pipeline _node_ to receive messages
from upstream pipeline _nodes_. Messages are fair-queued from among all
connected upstream _nodes_. The _zmq_send()_ function is not implemented for
this socket type.
[horizontal]
.Summary of ZMQ_PULL characteristics
Compatible peer sockets:: 'ZMQ_PUSH'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Block
Scatter-gather pattern
~~~~~~~~~~~~~~~~
The scatter-gather pattern is the thread-safe version of the pipeline pattern.
The scatter-gather pattern is used for distributing data to _nodes_ arranged in
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
is connected to at least one _node_. When a pipeline stage is connected to
multiple _nodes_ data is round-robined among all connected _nodes_.
ZMQ_SCATTER
^^^^^^^^
A socket of type 'ZMQ_SCATTER' is used by a scatter-gather _node_ to send messages
to downstream scatter-gather _nodes_. Messages are round-robined to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.
When a 'ZMQ_SCATTER' socket enters the 'mute' state due to having reached the
high water mark for all downstream _nodes_, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
then any linkzmq:zmq_send[3] operations on the socket shall block until the mute
state ends or at least one downstream _node_ becomes available for sending;
messages are not discarded.
NOTE: 'ZMQ_SCATTER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.
[horizontal]
.Summary of ZMQ_SCATTER characteristics
Compatible peer sockets:: 'ZMQ_SCATTER'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Round-robin
Action in mute state:: Block
ZMQ_GATHER
^^^^^^^^
A socket of type 'ZMQ_GATHER' is used by a scatter-gather _node_ to receive messages
from upstream scatter-gather _nodes_. Messages are fair-queued from among all
connected upstream _nodes_. The _zmq_send()_ function is not implemented for
this socket type.
NOTE: 'ZMQ_GATHER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.
[horizontal]
.Summary of ZMQ_GATHER characteristics
Compatible peer sockets:: 'ZMQ_GATHER'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Block
Exclusive pair pattern
~~~~~~~~~~~~~~~~~~~~~~
The exclusive pair pattern is used to connect a peer to precisely one other
peer. This pattern is used for inter-thread communication across the inproc
transport.
The exclusive pair pattern is formally defined by http://rfc.zeromq.org/spec:31.
ZMQ_PAIR
^^^^^^^^
A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one
time. No message routing or filtering is performed on messages sent over a
'ZMQ_PAIR' socket.
When a 'ZMQ_PAIR' socket enters the 'mute' state due to having reached the
high water mark for the connected peer, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
any linkzmq:zmq_send[3] operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.
While 'ZMQ_PAIR' sockets can be used over transports other than linkzmq:zmq_inproc[7],
their inability to auto-reconnect coupled with the fact new incoming connections will
be terminated while any previous connections (including ones in a closing state)
exist makes them unsuitable for TCP in most cases.
NOTE: 'ZMQ_PAIR' sockets are designed for inter-thread communication across
the linkzmq:zmq_inproc[7] transport and do not implement functionality such
as auto-reconnection.
[horizontal]
.Summary of ZMQ_PAIR characteristics
Compatible peer sockets:: 'ZMQ_PAIR'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Incoming routing strategy:: N/A
Outgoing routing strategy:: N/A
Action in mute state:: Block
Peer-to-peer pattern
~~~~~~~~~~~~~~~~~~~~~~
The peer-to-peer pattern is used to connect a peer to multiple peers.
Peer can both connect and bind and mix both of them with the same socket.
The peer-to-peer pattern is useful to build peer-to-peer networks (e.g zyre, bitcoin, torrent)
where a peer can both accept connections from other peers or connect to them.
NOTE: Peer-to-peer is still in draft phase.
ZMQ_PEER
^^^^^^^^
A 'ZMQ_PEER' socket talks to a set of 'ZMQ_PEER' sockets.
To connect and fetch the 'routing_id' of the peer use linkzmq:zmq_connect_peer[3].
Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with linkzmq:zmq_msg_routing_id[3].
To send a message to a given 'ZMQ_PEER' peer the application must set the peer's
'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3].
If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the peer is full, the send call shall block, unless ZMQ_DONTWAIT is
used in the send, in which case it shall fail with EAGAIN. The 'ZMQ_PEER'
socket shall not drop messages in any case.
NOTE: 'ZMQ_PEER' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data.
[horizontal]
.Summary of ZMQ_PEER characteristics
Compatible peer sockets:: 'ZMQ_PEER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Return EAGAIN
Channel pattern
~~~~~~~~~~~~~~~~~~~~~~
The channel pattern is the thread-safe version of the exclusive pair pattern.
The channel pattern is used to connect a peer to precisely one other
peer. This pattern is used for inter-thread communication across the inproc
transport.
NOTE: Channel is still in draft phase.
ZMQ_CHANNEL
^^^^^^^^
A socket of type 'ZMQ_CHANNEL' can only be connected to a single peer at any one
time. No message routing or filtering is performed on messages sent over a
'ZMQ_CHANNEL' socket.
When a 'ZMQ_CHANNEL' socket enters the 'mute' state due to having reached the
high water mark for the connected peer, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
any linkzmq:zmq_send[3] operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.
While 'ZMQ_CHANNEL' sockets can be used over transports other than linkzmq:zmq_inproc[7],
their inability to auto-reconnect coupled with the fact new incoming connections will
be terminated while any previous connections (including ones in a closing state)
exist makes them unsuitable for TCP in most cases.
NOTE: 'ZMQ_CHANNEL' sockets are designed for inter-thread communication across
the linkzmq:zmq_inproc[7] transport and do not implement functionality such
as auto-reconnection.
NOTE: 'ZMQ_CHANNEL' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.
[horizontal]
.Summary of ZMQ_CHANNEL characteristics
Compatible peer sockets:: 'ZMQ_CHANNEL'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Incoming routing strategy:: N/A
Outgoing routing strategy:: N/A
Action in mute state:: Block
Native Pattern
~~~~~~~~~~~~~~
The native pattern is used for communicating with TCP peers and allows
asynchronous requests and replies in either direction.
ZMQ_STREAM
^^^^^^^^^^
A socket of type 'ZMQ_STREAM' is used to send and receive TCP data from a
non-0MQ peer, when using the tcp:// transport. A 'ZMQ_STREAM' socket can
act as client and/or server, sending and/or receiving TCP data asynchronously.
When receiving TCP data, a 'ZMQ_STREAM' socket shall prepend a message part
containing the _routing id_ of the originating peer to the message before passing
it to the application. Messages received are fair-queued from among all
connected peers.
When sending TCP data, a 'ZMQ_STREAM' socket shall remove the first part of the
message and use it to determine the _routing id_ of the peer the message shall be
routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.
To open a connection to a server, use the zmq_connect call, and then fetch the
socket routing id using the zmq_getsockopt call with the ZMQ_ROUTING_ID option.
To close a specific connection, send the routing id frame followed by a
zero-length message (see EXAMPLE section).
When a connection is made, a zero-length message will be received by the
application. Similarly, when the peer disconnects (or the connection is lost),
a zero-length message will be received by the application.
You must send one routing id frame followed by one data frame. The ZMQ_SNDMORE
flag is required for routing id frames but is ignored on data frames.
[horizontal]
.Summary of ZMQ_STREAM characteristics
Compatible peer sockets:: none.
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: EAGAIN
Request-reply pattern
~~~~~~~~~~~~~~~~~~~~~
The request-reply pattern is used for sending requests from a ZMQ_REQ _client_
to one or more ZMQ_REP _services_, and receiving subsequent replies to each
request sent.
The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28.
ZMQ_REQ
^^^^^^^
A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
receive replies from a _service_. This socket type allows only an alternating
sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
request sent is round-robined among all _services_, and each reply received is
matched with the last issued request.
For connection-oriented transports, If the ZMQ_IMMEDIATE option is set and there
is no service available, then any send operation on the socket shall block until
at least one _service_ becomes available. The REQ socket shall not discard messages.
[horizontal]
.Summary of ZMQ_REQ characteristics
Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER'
Direction:: Bidirectional
Send/receive pattern:: Send, Receive, Send, Receive, ...
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Last peer
Action in mute state:: Block
ZMQ_REP
^^^^^^^
A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
send replies to a _client_. This socket type allows only an alternating
sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
request received is fair-queued from among all _clients_, and each reply sent
is routed to the _client_ that issued the last request. If the original
requester does not exist any more the reply is silently discarded.
[horizontal]
.Summary of ZMQ_REP characteristics
Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER'
Direction:: Bidirectional
Send/receive pattern:: Receive, Send, Receive, Send, ...
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: Last peer
ZMQ_DEALER
^^^^^^^^^^
A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending
request/reply sockets. Each message sent is round-robined among all connected
peers, and each message received is fair-queued from all connected peers.
When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the
high water mark for all peers, or, for connection-oriented transports, if the
ZMQ_IMMEDIATE option is set and there are no peers at all, then any
linkzmq:zmq_send[3] operations on the socket shall block until the mute state
ends or at least one peer becomes available for sending; messages are not discarded.
When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
must consist of an empty message part, the _delimiter_, followed by one or more
_body parts_.
[horizontal]
.Summary of ZMQ_DEALER characteristics
Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Fair-queued
Action in mute state:: Block
ZMQ_ROUTER
^^^^^^^^^^
A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending
request/reply sockets. When receiving messages a 'ZMQ_ROUTER' socket shall
prepend a message part containing the _routing id_ of the originating peer to the
message before passing it to the application. Messages received are fair-queued
from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
remove the first part of the message and use it to determine the _routing id _ of
the peer the message shall be routed to. If the peer does not exist anymore, or
has never existed, the message shall be silently discarded. However, if
'ZMQ_ROUTER_MANDATORY' socket option is set to '1', the socket shall fail
with EHOSTUNREACH in both cases.
When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
high water mark for all peers, then any messages sent to the socket shall be dropped
until the mute state ends. Likewise, any messages routed to a peer for which
the individual high water mark has been reached shall also be dropped. If,
'ZMQ_ROUTER_MANDATORY' is set to '1', the socket shall block or return EAGAIN in
both cases.
When a 'ZMQ_ROUTER' socket has 'ZMQ_ROUTER_MANDATORY' flag set to '1', the
socket shall generate 'ZMQ_POLLIN' events upon reception of messages from one
or more peers. Likewise, the socket shall generate 'ZMQ_POLLOUT' events when
at least one message can be sent to one or more peers.
When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
_routing id_ of the originating peer each message received shall contain an empty
_delimiter_ message part. Hence, the entire structure of each received message
as seen by the application becomes: one or more _routing id_ parts, _delimiter_
part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
application must include the _delimiter_ part.
[horizontal]
.Summary of ZMQ_ROUTER characteristics
Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Drop (see text)
RETURN VALUE
------------
The _zmq_socket()_ function shall return an opaque handle to the newly created
socket if successful. Otherwise, it shall return NULL and set 'errno' to one of
the values defined below.
ERRORS
------
*EINVAL*::
The requested socket 'type' is invalid.
*EFAULT*::
The provided 'context' is invalid.
*EMFILE*::
The limit on the total number of open 0MQ sockets has been reached.
*ETERM*::
The context specified was shutdown or terminated.
EXAMPLE
-------
.Creating a simple HTTP server using ZMQ_STREAM
----
void *ctx = zmq_ctx_new ();
assert (ctx);
/* Create ZMQ_STREAM socket */
void *socket = zmq_socket (ctx, ZMQ_STREAM);
assert (socket);
int rc = zmq_bind (socket, "tcp://*:8080");
assert (rc == 0);
/* Data structure to hold the ZMQ_STREAM routing id */
uint8_t routing_id [256];
size_t routing_id_size = 256;
/* Data structure to hold the ZMQ_STREAM received data */
uint8_t raw [256];
size_t raw_size = 256;
while (1) {
/* Get HTTP request; routing id frame and then request */
routing_id_size = zmq_recv (socket, routing_id, 256, 0);
assert (routing_id_size > 0);
do {
raw_size = zmq_recv (socket, raw, 256, 0);
assert (raw_size >= 0);
} while (raw_size == 256);
/* Prepares the response */
char http_response [] =
"HTTP/1.0 200 OK\r\n"
"Content-Type: text/plain\r\n"
"\r\n"
"Hello, World!";
/* Sends the routing id frame followed by the response */
zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
zmq_send (socket, http_response, strlen (http_response), 0);
/* Closes the connection by sending the routing id frame followed by a zero response */
zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
zmq_send (socket, 0, 0, 0);
}
zmq_close (socket);
zmq_ctx_destroy (ctx);
----
SEE ALSO
--------
linkzmq:zmq_init[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq[7]
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>.

296
vendor/ZMQ/doc/zmq_socket_monitor.txt vendored Normal file
View File

@@ -0,0 +1,296 @@
zmq_socket_monitor(3)
=====================
NAME
----
zmq_socket_monitor - monitor socket events
SYNOPSIS
--------
*int zmq_socket_monitor (void '*socket', char '*endpoint', int 'events');*
DESCRIPTION
-----------
The _zmq_socket_monitor()_ method lets an application thread track
socket events (like connects) on a ZeroMQ socket. Each call to this
method creates a 'ZMQ_PAIR' socket and binds that to the specified
inproc:// 'endpoint'. To collect the socket events, you must create
your own 'ZMQ_PAIR' socket, and connect that to the endpoint.
Note that there is also a DRAFT function linkzmq:zmq_socket_monitor_versioned[3],
which allows to subscribe to events that provide more information.
Calling zmq_socket_monitor is equivalent to calling 'zmq_socket_monitor_versioned'
with the 'event_version' parameter set to 1, with the exception of error cases.
The 'events' argument is a bitmask of the socket events you wish to
monitor, see 'Supported events' below. To monitor all events, use the
event value ZMQ_EVENT_ALL. NOTE: as new events are added, the catch-all
value will start returning them. An application that relies on a strict
and fixed sequence of events must not use ZMQ_EVENT_ALL in order to
guarantee compatibility with future versions.
Each event is sent as two frames. The first frame contains an event
number (16 bits), and an event value (32 bits) that provides additional
data according to the event number. The second frame contains a string
that specifies the affected endpoint.
----
The _zmq_socket_monitor()_ method supports only connection-oriented
transports, that is, TCP, IPC, and TIPC.
----
Supported events
----------------
ZMQ_EVENT_CONNECTED
~~~~~~~~~~~~~~~~~~~
The socket has successfully connected to a remote peer. The event value
is the file descriptor (FD) of the underlying network socket. Warning:
there is no guarantee that the FD is still valid by the time your code
receives this event.
ZMQ_EVENT_CONNECT_DELAYED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request on the socket is pending. The event value is unspecified.
ZMQ_EVENT_CONNECT_RETRIED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request failed, and is now being retried. The event value is the
reconnect interval in milliseconds. Note that the reconnect interval is
recalculated at each retry.
ZMQ_EVENT_LISTENING
~~~~~~~~~~~~~~~~~~~
The socket was successfully bound to a network interface. The event value
is the FD of the underlying network socket. Warning: there is no guarantee
that the FD is still valid by the time your code receives this event.
ZMQ_EVENT_BIND_FAILED
~~~~~~~~~~~~~~~~~~~~~
The socket could not bind to a given interface. The event value is the
errno generated by the system bind call.
ZMQ_EVENT_ACCEPTED
~~~~~~~~~~~~~~~~~~
The socket has accepted a connection from a remote peer. The event value is
the FD of the underlying network socket. Warning: there is no guarantee that
the FD is still valid by the time your code receives this event.
ZMQ_EVENT_ACCEPT_FAILED
~~~~~~~~~~~~~~~~~~~~~~~
The socket has rejected a connection from a remote peer. The event value is
the errno generated by the accept call.
ZMQ_EVENT_CLOSED
~~~~~~~~~~~~~~~~
The socket was closed. The event value is the FD of the (now closed) network
socket.
ZMQ_EVENT_CLOSE_FAILED
~~~~~~~~~~~~~~~~~~~~~~
The socket close failed. The event value is the errno returned by the system
call. Note that this event occurs only on IPC transports.
ZMQ_EVENT_DISCONNECTED
~~~~~~~~~~~~~~~~~~~~~~
The socket was disconnected unexpectedly. The event value is the FD of the
underlying network socket. Warning: this socket will be closed.
ZMQ_EVENT_MONITOR_STOPPED
~~~~~~~~~~~~~~~~~~~~~~~~~
Monitoring on this socket ended.
ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unspecified error during handshake.
The event value is an errno.
ZMQ_EVENT_HANDSHAKE_SUCCEEDED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake succeeded.
The event value is unspecified.
ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to some mechanism protocol
error, either between the ZMTP mechanism peers, or between the mechanism
server and the ZAP handler. This indicates a configuration or implementation
error in either peer resp. the ZAP handler.
The event value is one of the ZMQ_PROTOCOL_ERROR_* values:
ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE
ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA
ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC
ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH
ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY
ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID
ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA
ZMQ_EVENT_HANDSHAKE_FAILED_AUTH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to an authentication failure.
The event value is the status code returned by the ZAP handler (i.e. 300,
400 or 500).
RETURN VALUE
------------
The _zmq_socket_monitor()_ function returns a value of 0 or greater if
successful. Otherwise it returns `-1` and sets 'errno' to one of the values
defined below.
ERRORS
------
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported. Monitor sockets are
required to use the inproc:// transport.
*EINVAL*::
The endpoint supplied is invalid.
EXAMPLE
-------
.Monitoring client and server sockets
----
// Read one event off the monitor socket; return value and address
// by reference, if not null, and event number by value. Returns -1
// in case of error.
static int
get_monitor_event (void *monitor, int *value, char **address)
{
// First frame in message contains event number and value
zmq_msg_t msg;
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (zmq_msg_more (&msg));
uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
uint16_t event = *(uint16_t *) (data);
if (value)
*value = *(uint32_t *) (data + 2);
// Second frame in message contains event address
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (!zmq_msg_more (&msg));
if (address) {
uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
size_t size = zmq_msg_size (&msg);
*address = (char *) malloc (size + 1);
memcpy (*address, data, size);
(*address)[size] = 0;
}
return event;
}
int main (void)
{
void *ctx = zmq_ctx_new ();
assert (ctx);
// We'll monitor these two sockets
void *client = zmq_socket (ctx, ZMQ_DEALER);
assert (client);
void *server = zmq_socket (ctx, ZMQ_DEALER);
assert (server);
// Socket monitoring only works over inproc://
int rc = zmq_socket_monitor (client, "tcp://127.0.0.1:9999", 0);
assert (rc == -1);
assert (zmq_errno () == EPROTONOSUPPORT);
// Monitor all events on client and server sockets
rc = zmq_socket_monitor (client, "inproc://monitor-client", ZMQ_EVENT_ALL);
assert (rc == 0);
rc = zmq_socket_monitor (server, "inproc://monitor-server", ZMQ_EVENT_ALL);
assert (rc == 0);
// Create two sockets for collecting monitor events
void *client_mon = zmq_socket (ctx, ZMQ_PAIR);
assert (client_mon);
void *server_mon = zmq_socket (ctx, ZMQ_PAIR);
assert (server_mon);
// Connect these to the inproc endpoints so they'll get events
rc = zmq_connect (client_mon, "inproc://monitor-client");
assert (rc == 0);
rc = zmq_connect (server_mon, "inproc://monitor-server");
assert (rc == 0);
// Now do a basic ping test
rc = zmq_bind (server, "tcp://127.0.0.1:9998");
assert (rc == 0);
rc = zmq_connect (client, "tcp://127.0.0.1:9998");
assert (rc == 0);
bounce (client, server);
// Close client and server
close_zero_linger (client);
close_zero_linger (server);
// Now collect and check events from both sockets
int event = get_monitor_event (client_mon, NULL, NULL);
if (event == ZMQ_EVENT_CONNECT_DELAYED)
event = get_monitor_event (client_mon, NULL, NULL);
assert (event == ZMQ_EVENT_CONNECTED);
event = get_monitor_event (client_mon, NULL, NULL);
assert (event == ZMQ_EVENT_HANDSHAKE_SUCCEEDED);
event = get_monitor_event (client_mon, NULL, NULL);
assert (event == ZMQ_EVENT_MONITOR_STOPPED);
// This is the flow of server events
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_LISTENING);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_ACCEPTED);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_HANDSHAKE_SUCCEEDED);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_CLOSED);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_MONITOR_STOPPED);
// Close down the sockets
close_zero_linger (client_mon);
close_zero_linger (server_mon);
zmq_ctx_term (ctx);
return 0 ;
}
----
SEE ALSO
--------
linkzmq:zmq[7]
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>.

396
vendor/ZMQ/doc/zmq_socket_monitor_versioned.txt vendored Normal file
View File

@@ -0,0 +1,396 @@
zmq_socket_monitor_versioned(3)
===============================
NAME
----
zmq_socket_monitor_versioned - monitor socket events
SYNOPSIS
--------
*int zmq_socket_monitor_versioned (void '*socket', char '*endpoint', uint64_t 'events', int 'event_version', int 'type');*
*int zmq_socket_monitor_pipes_stats (void '*socket');*
DESCRIPTION
-----------
The _zmq_socket_monitor_versioned()_ method lets an application thread track
socket events (like connects) on a ZeroMQ socket. Each call to this
method creates a 'ZMQ_PAIR' socket and binds that to the specified
inproc:// 'endpoint'. To collect the socket events, you must create
your own 'ZMQ_PAIR' socket, and connect that to the endpoint.
The 'events' argument is a bitmask of the socket events you wish to
monitor, see 'Supported events' below. To monitor all events for a version, use
the event value ZMQ_EVENT_ALL_V<version>, e.g. ZMQ_EVENT_ALL_V1. For non-DRAFT event
versions, this value will not change in the future, so new event types will only be
added in new versions (note that this is a change over zmq_socket_monitor and the
unversioned ZMQ_EVENT_ALL).
Note that event_version 2 is currently in DRAFT mode. The protocol may be
changed at any time for event_versions in DRAFT.
ZMQ_CURRENT_EVENT_VERSION and ZMQ_CURRENT_EVENT_VERSION_DRAFT are always defined
to the most recent stable or DRAFT event version, which are currently 1 resp. 2
This page describes the protocol for 'event_version' 2 only. For the protocol
used with 'event_version' 1, please refer to linkzmq:zmq_socket_monitor[3].
Each event is sent in multiple frames. The first frame contains an event
number (64 bits). The number and content of further frames depend on this
event number.
Unless it is specified differently, the second frame contains the number of
value frames that will follow it as a 64 bits integer. The third frame to N-th
frames contain an event value (64 bits) that provides additional data according
to the event number. Each event type might have a different number of values.
The second-to-last and last frames contain strings that specifies the affected
connection or endpoint. The former frame contains a string denoting the local
endpoint, while the latter frame contains a string denoting the remote endpoint.
Either of these may be empty, depending on the event type and whether the
connection uses a bound or connected local endpoint.
Note that the format of the second and further frames, and also the number of
frames, may be different for events added in the future.
The 'type' argument is used to specify the type of the monitoring socket.
Supported types are 'ZMQ_PAIR', 'ZMQ_PUB' and 'ZMQ_PUSH'. Note that consumers
of the events will have to be compatible with the socket type, for instance a
monitoring socket of type 'ZMQ_PUB' will require consumers of type 'ZMQ_SUB'.
In the case that the monitoring socket type is of 'ZMQ_PUB', the multipart
message topic is the event number, thus consumers should subscribe to the
events they want to receive.
The _zmq_socket_monitor_pipes_stats()_ method triggers an event of type
ZMQ_EVENT_PIPES_STATS for each connected peer of the monitored socket.
NOTE: _zmq_socket_monitor_pipes_stats()_ is in DRAFT state.
----
Monitoring events are only generated by some transports: At the moment these
are SOCKS, TCP, IPC, and TIPC. Note that it is not an error to call
'zmq_socket_monitor_versioned' on a socket that is connected or bound to some
other transport, as this may not be known at the time
'zmq_socket_monitor_versioned' is called. Also, a socket can be connected/bound
to multiple endpoints using different transports.
----
Supported events (v1)
----------------
ZMQ_EVENT_CONNECTED
~~~~~~~~~~~~~~~~~~~
The socket has successfully connected to a remote peer. The event value
is the file descriptor (FD) of the underlying network socket. Warning:
there is no guarantee that the FD is still valid by the time your code
receives this event.
ZMQ_EVENT_CONNECT_DELAYED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request on the socket is pending. The event value is unspecified.
ZMQ_EVENT_CONNECT_RETRIED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request failed, and is now being retried. The event value is the
reconnect interval in milliseconds. Note that the reconnect interval is
recalculated for each retry.
ZMQ_EVENT_LISTENING
~~~~~~~~~~~~~~~~~~~
The socket was successfully bound to a network interface. The event value
is the FD of the underlying network socket. Warning: there is no guarantee
that the FD is still valid by the time your code receives this event.
ZMQ_EVENT_BIND_FAILED
~~~~~~~~~~~~~~~~~~~~~
The socket could not bind to a given interface. The event value is the
errno generated by the system bind call.
ZMQ_EVENT_ACCEPTED
~~~~~~~~~~~~~~~~~~
The socket has accepted a connection from a remote peer. The event value is
the FD of the underlying network socket. Warning: there is no guarantee that
the FD is still valid by the time your code receives this event.
ZMQ_EVENT_ACCEPT_FAILED
~~~~~~~~~~~~~~~~~~~~~~~
The socket has rejected a connection from a remote peer. The event value is
the errno generated by the accept call.
ZMQ_EVENT_CLOSED
~~~~~~~~~~~~~~~~
The socket was closed. The event value is the FD of the (now closed) network
socket.
ZMQ_EVENT_CLOSE_FAILED
~~~~~~~~~~~~~~~~~~~~~~
The socket close failed. The event value is the errno returned by the system
call. Note that this event occurs only on IPC transports.
ZMQ_EVENT_DISCONNECTED
~~~~~~~~~~~~~~~~~~~~~~
The socket was disconnected unexpectedly. The event value is the FD of the
underlying network socket. Warning: this socket will be closed.
ZMQ_EVENT_MONITOR_STOPPED
~~~~~~~~~~~~~~~~~~~~~~~~~
Monitoring on this socket ended.
ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unspecified error during handshake.
The event value is an errno.
ZMQ_EVENT_HANDSHAKE_SUCCEEDED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake succeeded.
The event value is unspecified.
ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to some mechanism protocol
error, either between the ZMTP mechanism peers, or between the mechanism
server and the ZAP handler. This indicates a configuration or implementation
error in either peer resp. the ZAP handler.
The event value is one of the ZMQ_PROTOCOL_ERROR_* values:
ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE
ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA
ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC
ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH
ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY
ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID
ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA
ZMQ_EVENT_HANDSHAKE_FAILED_AUTH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to an authentication failure.
The event value is the status code returned by the ZAP handler (i.e. 300,
400 or 500).
----
Supported events (v2)
----------------
ZMQ_EVENT_PIPE_STATS
~~~~~~~~~~~~~~~~~~~~
This event provides two values, the number of messages in each of the two
queues associated with the returned endpoint (respectively egress and ingress).
This event only triggers after calling the function
_zmq_socket_monitor_pipes_stats()_.
NOTE: this measurement is asynchronous, so by the time the message is received
the internal state might have already changed.
NOTE: when the monitored socket and the monitor are not used in a poll, the
event might not be delivered until an API has been called on the monitored
socket, like zmq_getsockopt for example (the option is irrelevant).
NOTE: in DRAFT state, not yet available in stable releases.
RETURN VALUE
------------
The _zmq_socket_monitor()_ and _zmq_socket_monitor_pipes_stats()_ functions
return a value of 0 or greater if successful. Otherwise they return `-1` and
set 'errno' to one of the values defined below.
ERRORS - _zmq_socket_monitor()_
-------------------------------
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*EPROTONOSUPPORT*::
The transport protocol of the monitor 'endpoint' is not supported. Monitor
sockets are required to use the inproc:// transport.
*EINVAL*::
The monitor 'endpoint' supplied does not exist or the specified socket 'type'
is not supported.
ERRORS - _zmq_socket_monitor_pipes_stats()_
-------------------------------------------
*ENOTSOCK*::
The 'socket' parameter was not a valid 0MQ socket.
*EINVAL*::
The socket did not have monitoring enabled.
*EAGAIN*::
The monitored socket did not have any connections to monitor yet.
EXAMPLE
-------
.Monitoring client and server sockets
----
// Read one event off the monitor socket; return values and addresses
// by reference, if not null, and event number by value. Returns -1
// in case of error.
static uint64_t
get_monitor_event (void *monitor, uint64_t *value, char **local_address, char **remote_address)
{
// First frame in message contains event number
zmq_msg_t msg;
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (zmq_msg_more (&msg));
uint64_t event;
memcpy (&event, zmq_msg_data (&msg), sizeof (event));
zmq_msg_close (&msg);
// Second frame in message contains the number of values
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (zmq_msg_more (&msg));
uint64_t value_count;
memcpy (&value_count, zmq_msg_data (&msg), sizeof (value_count));
zmq_msg_close (&msg);
for (uint64_t i = 0; i < value_count; ++i) {
// Subsequent frames in message contain event values
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (zmq_msg_more (&msg));
if (value_ && value_ + i)
memcpy (value_ + i, zmq_msg_data (&msg), sizeof (*value_));
zmq_msg_close (&msg);
}
// Second-to-last frame in message contains local address
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (zmq_msg_more (&msg));
if (local_address_) {
uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
size_t size = zmq_msg_size (&msg);
*local_address_ = (char *) malloc (size + 1);
memcpy (*local_address_, data, size);
(*local_address_)[size] = 0;
}
zmq_msg_close (&msg);
// Last frame in message contains remote address
zmq_msg_init (&msg);
if (zmq_msg_recv (&msg, monitor, 0) == -1)
return -1; // Interrupted, presumably
assert (!zmq_msg_more (&msg));
if (remote_address_) {
uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
size_t size = zmq_msg_size (&msg);
*remote_address_ = (char *) malloc (size + 1);
memcpy (*remote_address_, data, size);
(*remote_address_)[size] = 0;
}
zmq_msg_close (&msg);
return event;
}
int main (void)
{
void *ctx = zmq_ctx_new ();
assert (ctx);
// We'll monitor these two sockets
void *client = zmq_socket (ctx, ZMQ_DEALER);
assert (client);
void *server = zmq_socket (ctx, ZMQ_DEALER);
assert (server);
// Socket monitoring only works over inproc://
int rc = zmq_socket_monitor_versioned (client, "tcp://127.0.0.1:9999", 0, 2);
assert (rc == -1);
assert (zmq_errno () == EPROTONOSUPPORT);
// Monitor all events on client and server sockets
rc = zmq_socket_monitor_versioned (client, "inproc://monitor-client", ZMQ_EVENT_ALL, 2);
assert (rc == 0);
rc = zmq_socket_monitor_versioned (server, "inproc://monitor-server", ZMQ_EVENT_ALL, 2);
assert (rc == 0);
// Create two sockets for collecting monitor events
void *client_mon = zmq_socket (ctx, ZMQ_PAIR);
assert (client_mon);
void *server_mon = zmq_socket (ctx, ZMQ_PAIR);
assert (server_mon);
// Connect these to the inproc endpoints so they'll get events
rc = zmq_connect (client_mon, "inproc://monitor-client");
assert (rc == 0);
rc = zmq_connect (server_mon, "inproc://monitor-server");
assert (rc == 0);
// Now do a basic ping test
rc = zmq_bind (server, "tcp://127.0.0.1:9998");
assert (rc == 0);
rc = zmq_connect (client, "tcp://127.0.0.1:9998");
assert (rc == 0);
bounce (client, server);
// Close client and server
close_zero_linger (client);
close_zero_linger (server);
// Now collect and check events from both sockets
int event = get_monitor_event (client_mon, NULL, NULL);
if (event == ZMQ_EVENT_CONNECT_DELAYED)
event = get_monitor_event (client_mon, NULL, NULL);
assert (event == ZMQ_EVENT_CONNECTED);
event = get_monitor_event (client_mon, NULL, NULL);
assert (event == ZMQ_EVENT_MONITOR_STOPPED);
// This is the flow of server events
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_LISTENING);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_ACCEPTED);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_CLOSED);
event = get_monitor_event (server_mon, NULL, NULL);
assert (event == ZMQ_EVENT_MONITOR_STOPPED);
// Close down the sockets
close_zero_linger (client_mon);
close_zero_linger (server_mon);
zmq_ctx_term (ctx);
return 0 ;
}
----
SEE ALSO
--------
linkzmq:zmq[7]
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>.

56
vendor/ZMQ/doc/zmq_strerror.txt vendored Normal file
View File

@@ -0,0 +1,56 @@
zmq_strerror(3)
===============
NAME
----
zmq_strerror - get 0MQ error message string
SYNOPSIS
--------
*const char *zmq_strerror (int 'errnum');*
DESCRIPTION
-----------
The _zmq_strerror()_ function shall return a pointer to an error message string
corresponding to the error number specified by the 'errnum' argument. As 0MQ
defines additional error numbers over and above those defined by the operating
system, applications should use _zmq_strerror()_ in preference to the standard
_strerror()_ function.
RETURN VALUE
------------
The _zmq_strerror()_ function shall return a pointer to an error message
string.
ERRORS
------
No errors are defined.
EXAMPLE
-------
.Displaying an error message when a 0MQ context cannot be initialised
----
void *ctx = zmq_init (1, 1, 0);
if (!ctx) {
printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
abort ();
}
----
SEE ALSO
--------
linkzmq:zmq[7]
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>.

142
vendor/ZMQ/doc/zmq_tcp.txt vendored Normal file
View File

@@ -0,0 +1,142 @@
zmq_tcp(7)
==========
NAME
----
zmq_tcp - 0MQ unicast transport using TCP
SYNOPSIS
--------
TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
applications over a network with 0MQ, using the TCP transport will likely be
your first choice.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the TCP transport, the transport is `tcp`, and the meaning of the
'address' part is defined below.
Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the TCP port number to use.
An 'interface' may be specified by either of the following:
* The wild-card `*`, meaning all available interfaces.
* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
representation.
* The non-portable interface name as defined by the operating system.
The TCP port number may be specified by:
* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.
When using ephemeral ports, the caller should retrieve the actual assigned
port using the ZMQ_LAST_ENDPOINT socket option. See linkzmq:zmq_getsockopt[3]
for details.
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the TCP port number to use.
You can optionally specify a 'source_endpoint' which will be used as the source
address for your connection; tcp://'source_endpoint';'endpoint', see the
'interface' description above for details.
A 'peer address' may be specified by either of the following:
* The DNS name of the peer.
* The IPv4 or IPv6 address of the peer, in its numeric representation.
Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is
used by the TCP transport can be found at <http://rfc.zeromq.org/spec:15>
HWM
---
For the TCP transport, the high water mark (HWM) mechanism works in conjunction
with the TCP socket buffers handled at OS level.
Depending on the OS and several other factors the size of such TCP buffers will
be different. Moreover TCP buffers provided by the OS will accomodate a varying
number of messages depending on the size of messages (unlike ZMQ HWM settings
the TCP socket buffers are measured in bytes and not messages).
This may result in apparently inexplicable behaviors: e.g., you may expect that
setting ZMQ_SNDHWM to 100 on a socket using TCP transport will have the effect
of blocking the transmission of the 101-th message if the receiver is slow.
This is very unlikely when using TCP transport since OS TCP buffers will typically
provide enough buffering to allow you sending much more than 100 messages.
Of course if the receiver is slow, transmitting on a TCP ZMQ socket will eventually trigger
the "mute state" of the socket; simply don't rely on the exact HWM value.
Obviously the same considerations apply for the receive HWM (see ZMQ_RCVHWM).
EXAMPLES
--------
.Assigning a local address to a socket
----
// TCP port 5555 on all available interfaces
rc = zmq_bind(socket, "tcp://*:5555");
assert (rc == 0);
// TCP port 5555 on the local loop-back interface on all platforms
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
// TCP port 5555 on the first Ethernet network interface on Linux
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----
.Connecting a socket
----
// Connecting using an IP address
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
// Connecting using a DNS name
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
// Connecting using a DNS name and bind to eth1
rc = zmq_connect(socket, "tcp://eth1:0;server1:5555");
assert (rc == 0);
// Connecting using a IP address and bind to an IP address
rc = zmq_connect(socket, "tcp://192.168.1.17:5555;192.168.1.1:5555");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]
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>.

66
vendor/ZMQ/doc/zmq_term.txt vendored Normal file
View File

@@ -0,0 +1,66 @@
zmq_term(3)
===========
NAME
----
zmq_term - terminate 0MQ context
SYNOPSIS
--------
*int zmq_term (void '*context');*
DESCRIPTION
-----------
The _zmq_term()_ function shall terminate the 0MQ context 'context'.
Context termination is performed in the following steps:
1. Any blocking operations currently in progress on sockets open within
'context' shall return immediately with an error code of ETERM. With the
exception of _zmq_close()_, any further operations on sockets open within
'context' shall fail with an error code of ETERM.
2. After interrupting all blocking calls, _zmq_term()_ shall _block_ until the
following conditions are satisfied:
* All sockets open within 'context' have been closed with _zmq_close()_.
* For each socket within 'context', all messages sent by the application
with _zmq_send()_ have either been physically transferred to a network
peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
option has expired.
For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
option in linkzmq:zmq_setsockopt[3].
This function is deprecated by linkzmq:zmq_ctx_term[3].
RETURN VALUE
------------
The _zmq_term()_ function shall return zero if successful. Otherwise it shall
return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EFAULT*::
The provided 'context' was invalid.
*EINTR*::
Termination was interrupted by a signal. It can be restarted if needed.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]
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>.

162
vendor/ZMQ/doc/zmq_timers.txt vendored Normal file
View File

@@ -0,0 +1,162 @@
zmq_timers(3)
============
NAME
----
zmq_timers - helper functions for cross-platform timers callbacks
SYNOPSIS
--------
*typedef void(zmq_timer_fn) (int 'timer_id', void *'arg');*
*void *zmq_timers_new (void);*
*int zmq_timers_destroy (void **'timers_p');*
*int zmq_timers_add (void *'timers', size_t 'interval', zmq_timer_fn 'handler', void *'arg');*
*int zmq_timers_cancel (void *'timers', int 'timer_id');*
*int zmq_timers_set_interval (void *'timers', int 'timer_id', size_t 'interval');*
*int zmq_timers_reset (void *'timers', int 'timer_id');*
*long zmq_timers_timeout (void *'timers');*
*int zmq_timers_execute (void *'timers');*
DESCRIPTION
-----------
The _zmq_timers_*_ functions provide cross-platform access to timers callbacks.
Once a timer has been registered, it will repeat at the specified interval until
it gets manually cancelled. To run the callbacks, _zmq_timers_execute_ must be
ran.
_zmq_timers_new_ and _zmq_timers_destroy_ manage the lifetime of a timer
instance. _zmq_timers_new_ creates and returns a new timer instance, while
_zmq_timers_destroy_ destroys it. A pointer to a valid timer must be passed
as the _timers_p_ argument of _zmq_timers_destroy_. In particular,
_zmq_timers_destroy_ may not be called multiple times for the same timer
instance. _zmq_timers_destroy_ sets the passed pointer to NULL in case of a
successful execution.
_zmq_timers_add_ and _zmq_timers_cancel_ manage the timers registered.
_zmq_timers_add_ registers a new _timer_ with a given instance. _timers_ must
point to a valid _timers_ object. The _interval_ parameter specifies the
expiration of the timer in milliseconds. _handler_ and _arg_ specify the callback
that will be invoked on expiration and the optional parameter that will be passed
through. The callback must be a valid function implementing the _zmq_timer_fn_
prototype. An ID will be returned that can be used to modify or cancel the timer.
_zmq_timers_cancel_ will cancel the timer associated with _timer_id_ from the
instance _timers_.
_zmq_timers_set_interval_ will set the expiration of the timer associated with
_timer_id_ from the instance _timers_ to _interval_ milliseconds into the future.
_zmq_timers_reset_ will restart the timer associated with _timer_id_ from the
instance _timers_.
_zmq_timers_timeout_ will return the time left in milliseconds until the next
timer registered with _timers_ expires.
_zmq_timers_execute_ will run callbacks of all expired timers from the instance
_timers_.
THREAD SAFETY
-------------
Like most other 0MQ objects, timers are not thread-safe. All operations must
be called from the same thread. Otherwise, behaviour is undefined.
RETURN VALUE
------------
_zmq_timers_new_ always returns a valid pointer to a poller.
All functions that return an int, return -1 in case of a failure. In that case,
zmq_errno() can be used to query the type of the error as described below.
_zmq_timers_timeout_ returns the time left in milliseconds until the next
timer registered with _timers_ expires, or -1 if there are no timers left.
All other functions return 0 in case of a successful execution.
ERRORS
------
On _zmq_timers_destroy_, _zmq_poller_cancel_, _zmq_timers_set_interval_,
_zmq_timers_reset_, zmq_timers_timeout_, and _zmq_timers_execute_:
*EFAULT*::
_timers_ did not point to a valid timer. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
On _zmq_timers_add_:
*EFAULT*::
_timers_ did not point to a valid timer or _handler_ did not point to a valid
function.
On _zmq_poller_cancel_, _zmq_timers_set_interval_ and zmq_timers_timeout_:
*EINVAL*::
_timer_id_ did not exist or was already cancelled.
EXAMPLE
-------
.Add one timer with a simple callback that changes a boolean.
----
void handler (int timer_id_, void *arg_)
{
(void) timer_id_; // Stop 'unused' compiler warnings
*((bool *) arg_) = true;
}
...
void *timers = zmq_timers_new ();
assert (timers);
bool timer_invoked = false;
const unsigned long full_timeout = 100;
int timer_id =
zmq_timers_add (timers, full_timeout, handler, &timer_invoked);
assert (timer_id);
// Timer should not have been invoked yet
int rc = zmq_timers_execute (timers);
assert (rc == 0);
// Wait half the time and check again
long timeout = zmq_timers_timeout (timers);
assert (rc != -1);
msleep (timeout / 2);
rc = zmq_timers_execute (timers);
assert (rc == 0);
// Wait until the end
rc = msleep (zmq_timers_timeout (timers));
assert (rc == 0);
assert (timer_invoked);
rc = zmq_timers_destroy (&timers);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq[7]
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>.

83
vendor/ZMQ/doc/zmq_tipc.txt vendored Normal file
View File

@@ -0,0 +1,83 @@
zmq_tipc(7)
==========
NAME
----
zmq_tipc - 0MQ unicast transport using TIPC
SYNOPSIS
--------
TIPC is a cluster IPC protocol with a location transparent addressing scheme.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the TIPC transport, the transport is `tipc`, and the meaning of the
'address' part is defined below.
Assigning a port name to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a port name to a socket using _zmq_bind()_ with the 'tipc'
transport, the 'endpoint' is defined in the form:
{type, lower, upper}
* Type is the numerical (u32) ID of your service.
* Lower and Upper specify a range for your service.
Publishing the same service with overlapping lower/upper ID's will
cause connection requests to be distributed over these in a round-robin
manner.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'tipc'
transport, the 'endpoint' shall be interpreted as a service ID, followed by a
comma and the instance ID.
The instance ID must be within the lower/upper range of a published port name
for the endpoint to be valid.
EXAMPLES
--------
.Assigning a local address to a socket
----
// Publish TIPC service ID 5555
rc = zmq_bind(socket, "tipc://{5555,0,0}");
assert (rc == 0);
// Publish TIPC service ID 5555 with a service range of 0-100
rc = zmq_bind(socket, "tipc://{5555,0,100}");
assert (rc == 0);
----
.Connecting a socket
----
// Connect to service 5555 instance id 50
rc = zmq_connect(socket, "tipc://{5555,50}");
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]
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>.

116
vendor/ZMQ/doc/zmq_udp.txt vendored Normal file
View File

@@ -0,0 +1,116 @@
zmq_udp(7)
==========
NAME
----
zmq_udp - 0MQ UDP multicast and unicast transport
SYNOPSIS
--------
UDP is unreliable protocol transport of data over IP networks.
UDP support both unicast and multicast communication.
DESCRIPTION
-----------
UDP transport can only be used with the 'ZMQ_RADIO' and
'ZMQ_DISH' socket types.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the UDP transport, the transport is `udp`.
The meaning of the 'address' part is defined below.
Binding a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With 'udp' we can only bind the 'ZMQ_DISH' socket type.
When binding a socket using _zmq_bind()_ with the 'udp'
transport the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the UDP port number to use.
An 'interface' may be specified by either of the following:
* The wild-card `*`, meaning all available interfaces.
* The name of the network interface (i.e. eth0, lo, wlan0 etc...)
* The primary address assigned to the interface, in its numeric representation.
* Multicast address in its numeric representation the socket should join.
The UDP port number may be specified a numeric value, usually above
1024 on POSIX systems.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
With 'udp' we can only connect the 'ZMQ_RADIO' socket type.
When connecting a socket to a peer address using _zmq_connect()_ with the 'udp'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the UDP port number to use.
A 'peer address' may be specified by either of the following:
* The IPv4 or IPv6 address of the peer, in its numeric representation
or using its hostname.
* Multicast address in its numeric representation.
EXAMPLES
--------
.Binding a socket
----
// Unicast - UDP port 5555 on all available interfaces
rc = zmq_bind(dish, "udp://*:5555");
assert (rc == 0);
// Unicast - UDP port 5555 on the local loop-back interface
rc = zmq_bind(dish, "udp://127.0.0.1:5555");
assert (rc == 0);
// Unicast - UDP port 5555 on interface eth1
rc = zmq_bind(dish, "udp://eth1:5555");
assert (rc == 0);
// Multicast - UDP port 5555 on a Multicast address
rc = zmq_bind(dish, "udp://239.0.0.1:5555");
assert (rc == 0);
// Same as above but joining only on interface eth0
rc = zmq_bind(dish, "udp://eth0;239.0.0.1:5555");
assert (rc == 0);
// Same as above using IPv6 multicast
rc = zmq_bind(dish, "udp://eth0;[ff02::1]:5555");
assert (rc == 0);
----
.Connecting a socket
----
// Connecting using an Unicast IP address
rc = zmq_connect(radio, "udp://192.168.1.1:5555");
assert (rc == 0);
// Connecting using a Multicast address
rc = zmq_connect(socket, "udp://239.0.0.1:5555);
assert (rc == 0);
// Connecting using a Multicast address using local interface wlan0
rc = zmq_connect(socket, "udp://wlan0;239.0.0.1:5555);
assert (rc == 0);
// Connecting to IPv6 multicast
rc = zmq_connect(socket, "udp://[ff02::1]:5555);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]
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>.

103
vendor/ZMQ/doc/zmq_unbind.txt vendored Normal file
View File

@@ -0,0 +1,103 @@
zmq_unbind(3)
==============
NAME
----
zmq_unbind - Stop accepting connections on a socket
SYNOPSIS
--------
int zmq_unbind (void '*socket', const char '*endpoint');
DESCRIPTION
-----------
The _zmq_unbind()_ function shall unbind a socket specified
by the 'socket' argument from the endpoint specified by the 'endpoint'
argument.
Addionally the incoming message queue associated with the endpoint will be
discarded. This means that after unbinding an endpoint it is possible to
received messages originating from that same endpoint if they were already
present in the incoming message queue before unbinding.
The 'endpoint' argument is as described in linkzmq:zmq_bind[3]
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' (described in linkzmq:zmq_tcp[7],
linkzmq:zmq_ipc[7], linkzmq:zmq_udp[7] and linkzmq:zmq_vmci[7]) was used in
_zmq_bind()_, the caller should use real 'endpoint' obtained from the
ZMQ_LAST_ENDPOINT socket option to unbind this 'endpoint' from a socket.
RETURN VALUE
------------
The _zmq_unbind()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ENOENT*::
The endpoint supplied was not previously bound.
EXAMPLES
--------
.Unbind a subscriber socket from a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_unbind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
----
.Unbind wild-card `*` binded socket
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Bind it to the system-assigned ephemeral port using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:*");
assert (rc == 0);
/* Obtain real endpoint */
const size_t buf_size = 32;
char buf[buf_size];
rc = zmq_getsockopt (socket, ZMQ_LAST_ENDPOINT, buf, (size_t *)&buf_size);
assert (rc == 0);
/* Unbind socket by real endpoint */
rc = zmq_unbind (socket, buf);
assert (rc == 0);
----
NOTE
----
Note that while the implementation is similar to _zmq_disconnect()_, the
semantics are different and the two functions should not be used
interchangeably. Bound sockets should be unbound, and connected sockets should
be disconnected.
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
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>.

54
vendor/ZMQ/doc/zmq_version.txt vendored Normal file
View File

@@ -0,0 +1,54 @@
zmq_version(3)
==============
NAME
----
zmq_version - report 0MQ library version
SYNOPSIS
--------
*void zmq_version (int '*major', int '*minor', int '*patch');*
DESCRIPTION
-----------
The _zmq_version()_ function shall fill in the integer variables pointed to by
the 'major', 'minor' and 'patch' arguments with the major, minor and patch level
components of the 0MQ library version.
This functionality is intended for applications or language bindings
dynamically linking to the 0MQ library that wish to determine the actual
version of the 0MQ library they are using.
RETURN VALUE
------------
There is no return value.
ERRORS
------
No errors are defined.
EXAMPLE
-------
.Printing out the version of the 0MQ library
----
int major, minor, patch;
zmq_version (&major, &minor, &patch);
printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch);
----
SEE ALSO
--------
linkzmq:zmq[7]
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>.

97
vendor/ZMQ/doc/zmq_vmci.txt vendored Normal file
View File

@@ -0,0 +1,97 @@
zmq_vmci(7)
===========
NAME
----
zmq_vmci - 0MQ transport over virtual machine communicatios interface (VMCI) sockets
SYNOPSIS
--------
The VMCI transport passes messages between VMware virtual machines running on the same host,
between virtual machine and the host and within virtual machines (inter-process transport like ipc).
NOTE: Communication between a virtual machine and the host is not supported on Mac OS X 10.9 and above.
ADDRESSING
----------
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.
For the VMCI transport, the transport is `vmci`, and the meaning of
the 'address' part is defined below.
Binding a socket
~~~~~~~~~~~~~~~~
When binding a 'socket' to a local address using _zmq_bind()_ with the 'vmci'
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the TCP port number to use.
An 'interface' may be specified by either of the following:
* The wild-card `*`, meaning all available interfaces.
* An integer returned by `VMCISock_GetLocalCID` or `@` (ZeroMQ will call VMCISock_GetLocalCID internally).
The port may be specified by:
* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'vmci'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the port number to use.
A 'peer address' must be a CID of the peer.
EXAMPLES
--------
.Assigning a local address to a socket
----
// VMCI port 5555 on all available interfaces
rc = zmq_bind(socket, "vmci://*:5555");
assert (rc == 0);
// VMCI port 5555 on the local loop-back interface on all platforms
cid = VMCISock_GetLocalCID();
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_bind(socket, endpoint);
assert (rc == 0);
----
.Connecting a socket
----
// Connecting using a CID
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_connect(socket, endpoint);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq[7]
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>.

51
vendor/ZMQ/doc/zmq_z85_decode.txt vendored Normal file
View File

@@ -0,0 +1,51 @@
zmq_z85_decode(3)
=================
NAME
----
zmq_z85_decode - decode a binary key from Z85 printable text
SYNOPSIS
--------
*uint8_t *zmq_z85_decode (uint8_t *dest, const char *string);*
DESCRIPTION
-----------
The _zmq_z85_decode()_ function shall decode 'string' into 'dest'.
The length of 'string' shall be divisible by 5. 'dest' must be large
enough for the decoded value (0.8 x strlen (string)).
The encoding shall follow the ZMQ RFC 32 specification.
RETURN VALUE
------------
The _zmq_z85_decode()_ function shall return 'dest' if successful, else it
shall return NULL.
EXAMPLE
-------
.Decoding a CURVE key
----
const char decoded [] = "rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7";
uint8_t public_key [32];
zmq_z85_decode (public_key, decoded);
----
SEE ALSO
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve_public[3]
linkzmq:zmq_curve[7]
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>.

58
vendor/ZMQ/doc/zmq_z85_encode.txt vendored Normal file
View File

@@ -0,0 +1,58 @@
zmq_z85_encode(3)
=================
NAME
----
zmq_z85_encode - encode a binary key as Z85 printable text
SYNOPSIS
--------
*char *zmq_z85_encode (char *dest, const uint8_t *data, size_t size);*
DESCRIPTION
-----------
The _zmq_z85_encode()_ function shall encode the binary block specified
by 'data' and 'size' into a string in 'dest'. The size of the binary block
must be divisible by 4. The 'dest' must have sufficient space for size * 1.25
plus 1 for a null terminator. A 32-byte CURVE key is encoded as 40 ASCII
characters plus a null terminator.
The encoding shall follow the ZMQ RFC 32 specification.
RETURN VALUE
------------
The _zmq_z85_encode()_ function shall return 'dest' if successful, else it
shall return NULL.
EXAMPLE
-------
.Encoding a CURVE key
----
#include <sodium.h>
uint8_t public_key [32];
uint8_t secret_key [32];
int rc = crypto_box_keypair (public_key, secret_key);
assert (rc == 0);
char encoded [41];
zmq_z85_encode (encoded, public_key, 32);
puts (encoded);
----
SEE ALSO
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve_public[3]
linkzmq:zmq_curve[7]
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>.