Skip to content

L
libzmq
Commit 1aee8640 authored by Martin Lucina's avatar Martin Lucina
Browse files
Options

Documentation rewrite

parent d790940f
Hide whitespace changes
Inline Side-by-side
Showing with 1298 additions and 973 deletions
doc/Makefile.am
View file @ 1aee8640
...@@ -4,8 +4,8 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \ ...@@ -4,8 +4,8 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \
zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \ zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \
zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_strerror.3 zmq_term.3 zmq_version.3
MAN7 = zmq.7 zmq_tcp.7 zmq_udp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \ MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
zmq_cpp.7 zmq_java.7 zmq_cpp.7
MAN_DOC = $(MAN1) $(MAN3) $(MAN7) MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
MAN_TXT = $(MAN1:%.1=%.txt) MAN_TXT = $(MAN1:%.1=%.txt)
......
doc/asciidoc.conf
View file @ 1aee8640
[paradef-default]
literal-style=template="literalparagraph"
[macros] [macros]
(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= (?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
...@@ -32,3 +35,8 @@ template::[header-declarations] ...@@ -32,3 +35,8 @@ template::[header-declarations]
</refnamediv> </refnamediv>
endif::backend-docbook[] endif::backend-docbook[]
endif::doctype-manpage[] endif::doctype-manpage[]
[replacements]
ifdef::backend-xhtml11[]
0MQ=ØMQ
endif::backend-xhtml11[]
doc/zmq.txt
View file @ 1aee8640
...@@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel ...@@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel
SYNOPSIS SYNOPSIS
-------- --------
0MQ is an extension of POSIX sockets. It is a library that augments standard *#include <zmq.h>*
networking sockets by special capabilities that you can otherwise get only
by using specialised "messaging middleware" products, such as automated
handling of connections and disconnections, delivery of a message to multiple
destinations, load balancing messages, sophisticated message filtering etc.
0MQ is designed to be extremely fast. Expected end-to-end latencies for *cc* ['flags'] 'files' *-lzmq* ['libraries']
messages passed over a LAN are in tens of microseconds. Expected
throughputs are to be measured in millions of messages per second.
0MQ is designed to be very thin. It requires no more than couple of
pages in resident memory and is thus well suited for any environment ranging
from small embedded devices, routers and cell phones to enterprise-scale
data centers.
0MQ runs on a wide range of operating systems and supports variety of processor DESCRIPTION
microarchitectures. -----------
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.
0MQ is accessible from a large set of programming languages. 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.
0MQ is fully open sourced LGPL-licensed software.
Context
CONTEXT ~~~~~~~
------- Before using any 0MQ library functions the caller must initialise a 0MQ
Each 0MQ socket lives within a specific context. Creating and destroying 'context' using _zmq_init()_. The following functions are provided to handle
context is a counterpart of library initialisation/deinitialisation as used initialisation and termination of a 'context':
elsewhere. Ability to create multiple contexts saves the day when an application
happens to link (indirectly and involuntarily) with several instances of 0MQ.
Initialise 0MQ context:: Initialise 0MQ context::
linkzmq:zmq_init[3] linkzmq:zmq_init[3]
Uninitialise 0MQ context:: Terminate 0MQ context::
linkzmq:zmq_term[3] linkzmq:zmq_term[3]
MESSAGES Thread safety
-------- ^^^^^^^^^^^^^
Message is a discrete unit of data passed between applications or components A 0MQ 'context' is thread safe and may be shared among as many application
of the same application. 0MQ message has no internal structure, it is an opaque threads as the application has requested using the _app_threads_ parameter to
BLOB. When writing data to or reading data from the message, you are free to _zmq_init()_, without any additional locking required on the part of the
use any of the many serialisation libraries available. Alternatively, you can caller. Each 0MQ socket belonging to a particular 'context' may only be used
use your own serialisation code. The latter option is especially useful when by *the thread that created it* using _zmq_socket()_.
migrating legacy applications to 0MQ - there's no need to break existing
message formats.
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 BLOBs.
The following functions are provided to work with messages:
Initialise a message:: Initialise a message::
linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_init_data[3]
Uninitialise a message:: Release a message::
linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_close[3]
Access message content:: Access message content::
...@@ -73,10 +83,21 @@ Message manipulation:: ...@@ -73,10 +83,21 @@ Message manipulation::
linkzmq:zmq_msg_move[3] linkzmq:zmq_msg_move[3]
SOCKETS Sockets
------- ~~~~~~~
0MQ sockets are very similar to POSIX sockets. See following manual pages to Standard sockets present a _synchronous_ interface to either connection-mode
understand them in depth. reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
asynchronous _message queue_, with the exact queueing semantics depending on
the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
_messaging patterns_ provided.
0MQ sockets being _asynchronous_ means that the timings of the physical
connection setup and teardown, reconnect and effective delivery are organized
by 0MQ itself, and that messages may be _queued_ in the event that a peer is
unavailable to receive them.
The following functions are provided to work with sockets:
Creating a socket:: Creating a socket::
linkzmq:zmq_socket[3] linkzmq:zmq_socket[3]
...@@ -91,82 +112,108 @@ Establishing a message flow:: ...@@ -91,82 +112,108 @@ Establishing a message flow::
linkzmq:zmq_bind[3] linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3] linkzmq:zmq_connect[3]
Sending & receiving messages:: Sending and receiving messages::
linkzmq:zmq_send[3] linkzmq:zmq_send[3]
linkzmq:zmq_flush[3] linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3] linkzmq:zmq_recv[3]
MULTIPLEXING Input/output multiplexing
------------ ^^^^^^^^^^^^^^^^^^^^^^^^^
0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX) 0MQ provides a mechanism for applications to multiplex input/output events over
in an asynchronous manner. a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
the standard _poll()_ system call, and is described in detail in
Poll for I/O events:: linkzmq:zmq_poll[3].
linkzmq:zmq_poll[3]
ERROR HANDLING
--------------
0MQ defines couple of non-POSIX error codes. Use following functions to handle
them neatly.
Convert error code into human readable string::
linkzmq:zmq_strerror[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.
TRANSPORTS The following transport mechanisms are provided:
----------
0MQ allows for using different underlying transport mechanisms (even multiple
at once). Each transport mechanism has its own advantages and drawbacks. For
detailed description of individual mechanisms check following manual pages:
TCP/IP transport:: Unicast transport using TCP::
linkzmq:zmq_tcp[7] linkzmq:zmq_tcp[7]
UDP reliable multicast transport:: Reliable multicast transport using PGM::
linkzmq:zmq_udp[7]
PGM reliable multicast transport::
linkzmq:zmq_pgm[7] linkzmq:zmq_pgm[7]
Inter-process transport:: Local inter-process communication transport::
linkzmq:zmq_ipc[7] linkzmq:zmq_ipc[7]
In-process (inter-thread) transport:: Local in-process (inter-thread) communication transport::
linkzmq:zmq_inproc[7] linkzmq:zmq_inproc[7]
DEVICES Devices
------- ~~~~~~~
Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
executables - devices - to serve as middle nodes in complex messaging building blocks intended to serve as intermediate nodes in complex messaging
topologies. For detailed description of individual devices check following topologies.
manual pages:
Forwarder device for PUB/SUB messaging:: The following devices are provided:
Forwarder device for request-response messaging::
linkzmq:zmq_queue[1]
Forwarder device for publish-subscribe messaging::
linkzmq:zmq_forwarder[1] linkzmq:zmq_forwarder[1]
Streamer device for UPSTREAM/DOWNSTREAM messaging:: Streamer device for parallelized pipeline messaging::
linkzmq:zmq_streamer[1] linkzmq:zmq_streamer[1]
Forwarder device for REQ/REP messaging::
linkzmq:zmq_queue[1]
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.
A _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
into error message strings. For further details refer to
linkzmq:zmq_strerror[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.
LANGUAGES
---------
0MQ manual pages provide info on C API. To find out how the your
favourite language API maps to C API and thus how to find relevant manual pages,
see following articles:
$$C++$$:: C++ language binding
linkzmq:zmq_cpp[7] ~~~~~~~~~~~~~~~~~~~~
The 0MQ distribution includes a $$C++$$ language binding, which is documented
separately in linkzmq:zmq_cpp[7].
Java::
linkzmq:zmq_java[7]
Other language bindings
~~~~~~~~~~~~~~~~~~~~~~~
Other language bindings (Python, Ruby, Java and more) are provided by members
of the 0MQ community and pointers can be found on the 0MQ website.
AUTHOR
------ AUTHORS
Martin Sustrik <sustrik at 250bpm dot com> -------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
RESOURCES
---------
Main web site: <http://www.zeromq.org/>
Report bugs to the 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.
doc/zmq_bind.txt
View file @ 1aee8640
...@@ -4,53 +4,66 @@ zmq_bind(3) ...@@ -4,53 +4,66 @@ zmq_bind(3)
NAME NAME
---- ----
zmq_bind - binds the socket to the specified address zmq_bind - assign a local address to a socket
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_bind (void *s, const char *addr);' *int zmq_bind (void '*socket', const char '*address');*
DESCRIPTION DESCRIPTION
----------- -----------
The function binds socket 's' to a particular transport. Actual semantics of the The _zmq_bind()_ function shall assign a local address specified by the
command depend on the underlying transport mechanism, however, in cases where 'address' argument to the socket referenced by the 'socket' argument.
peers connect in an asymmetric manner, 'zmq_bind' should be called first,
'zmq_connect' afterwards. Actual formats of 'addr' parameter are defined by
individual transports. For a list of supported transports have a look at
linkzmq:zmq[7] manual page.
Note that single socket can be bound (and connected) to The 'address' argument is a string consisting of two parts as follows:
arbitrary number of peers using different transport mechanisms. 'transport'://'endpoint'. The 'transport' part specifies the underlying
transport protocol to use. The meaning of the 'endpoint' part is specific to
the underlying transport protocol selected.
The following transports are defined:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'pgm', 'udp':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[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]
A single socket may have an arbitrary number of local addresses assigned to it
using _zmq_bind()_, while also being connected to an arbitrary number of peer
addresses using _zmq_connect()_.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_bind()_ function shall return zero if successful. Otherwise it shall
sets 'errno' to the appropriate value. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*EPROTONOSUPPORT*:: *EPROTONOSUPPORT*::
unsupported protocol. The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*:: *ENOCOMPATPROTO*::
protocol is not compatible with the socket type. The requested 'transport' protocol is not compatible with the socket type.
*EADDRINUSE*:: *EADDRINUSE*::
the given address is already in use. The given 'address' is already in use.
*EADDRNOTAVAIL*:: *EADDRNOTAVAIL*::
a nonexistent interface was requested or the requested address was not local. A nonexistent interface was requested or the requested 'address' was not local.
EXAMPLE EXAMPLE
------- -------
.Binding a publisher socket to an in-process and a TCP transport
---- ----
void *s = zmq_socket (context, ZMQ_PUB); /* Create a ZMQ_PUB socket */
assert (s); void *socket = zmq_socket (context, ZMQ_PUB);
int rc = zmq_bind (s, "inproc://my_publisher"); assert (socket);
/* Bind it to a in-process transport with the endpoint 'my_publisher' */
int rc = zmq_bind (socket, "inproc://my_publisher");
assert (rc == 0); assert (rc == 0);
rc = zmq_bind (s, "tcp://eth0:5555"); /* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
rc = zmq_bind (socket, "tcp://eth0:5555");
assert (rc == 0); assert (rc == 0);
---- ----
...@@ -62,6 +75,7 @@ linkzmq:zmq_socket[3] ...@@ -62,6 +75,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_close.txt
View file @ 1aee8640
...@@ -4,28 +4,29 @@ zmq_close(3) ...@@ -4,28 +4,29 @@ zmq_close(3)
NAME NAME
---- ----
zmq_close - destroys 0MQ socket zmq_close - close 0MQ socket
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_close (void *s);' *int zmq_close (void '*socket');*
DESCRIPTION DESCRIPTION
----------- -----------
Destroys 0MQ socket (one created using The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
'zmq_socket' function). All sockets have to be properly closed before the argument. All active connections on the socket shall be terminated and
application terminates, otherwise memory leaks will occur. Note that any resources associated with the socket shall be released. Any outstanding
outbound messages that haven't been psuhed to the network yet and any inbound messages sent with _zmq_send()_ but not yet physically sent to the network
messages that haven't been received by the application yet will be dropped on shall be dropped. Likewise, any outstanding messages physically received from
the socket shutdown. the network but not yet received by the application with _zmq_recv()_ shall
also be dropped.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_close()_ function shall return zero if successful. Otherwise it shall
sets 'errno' to the appropriate value. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -33,20 +34,14 @@ ERRORS ...@@ -33,20 +34,14 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
int rc = zmq_close (s);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_socket[3] linkzmq:zmq_socket[3]
linkzmq:zmq_term[3] linkzmq:zmq_term[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_connect.txt
View file @ 1aee8640
...@@ -4,49 +4,66 @@ zmq_connect(3) ...@@ -4,49 +4,66 @@ zmq_connect(3)
NAME NAME
---- ----
zmq_connect - connect the socket to the specified peer zmq_connect - connect a socket to a peer address
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_connect (void *s, const char *addr);' *int zmq_connect (void '*socket', const char '*address');*
DESCRIPTION DESCRIPTION
----------- -----------
The function connect socket 's' to the peer identified by 'addr'. Actual The _zmq_connect()_ function shall connect the socket referenced by the
semantics of the command depend on the underlying transport mechanism, 'socket' argument to a peer address specified by the 'address' argument.
however, in cases where peers connect in an asymmetric manner, 'zmq_bind'
should be called first, 'zmq_connect' afterwards. Formats of the 'addr'
parameter are defined by individual transports. For a list of supported
transports have a look at linkzmq:zmq[7] manual page.
Note that single socket can be connected (and bound) to The 'address' argument is a string consisting of two parts as follows:
arbitrary number of peers using different transport mechanisms. 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use. The meaning of the 'endpoint' part is specific to
the underlying transport protocol selected.
The following transports are defined:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'pgm', 'udp':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[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]
A single socket may be connected to an arbitrary number of peer addresses using
_zmq_connect()_, while also having an arbitrary number of local addresses
assigned to it using _zmq_bind()_.
NOTE: The connection will not be performed immediately but as needed by 0MQ.
Thus a successful invocation of _zmq_connect()_ does not indicate that a
physical connection was or can actually be established.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_connect()_ function shall return zero if successful. Otherwise it
sets 'errno' to the appropriate value. shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*EPROTONOSUPPORT*:: *EPROTONOSUPPORT*::
unsupported protocol. The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*:: *ENOCOMPATPROTO*::
protocol is not compatible with the socket type. The requested 'transport' protocol is not compatible with the socket type.
EXAMPLE EXAMPLE
------- -------
.Connecting a subscriber socket to an in-process and a TCP transport
---- ----
void *s = zmq_socket (context, ZMQ_SUB); /* Create a ZMQ_SUB socket */
assert (s); void *socket = zmq_socket (context, ZMQ_SUB);
int rc = zmq_connect (s, "inproc://my_publisher"); assert (socket);
/* Connect it to an in-process transport with the endpoint 'my_publisher' */
int rc = zmq_connect (socket, "inproc://my_publisher");
assert (rc == 0); assert (rc == 0);
rc = zmq_connect (s, "tcp://server001:5555"); /* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0); assert (rc == 0);
---- ----
...@@ -58,6 +75,7 @@ linkzmq:zmq_socket[3] ...@@ -58,6 +75,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_epgm.txt 0 → 120000
View file @ 1aee8640
zmq_pgm.txt
\ No newline at end of file
doc/zmq_flush.txt
View file @ 1aee8640
...@@ -4,56 +4,52 @@ zmq_flush(3) ...@@ -4,56 +4,52 @@ zmq_flush(3)
NAME NAME
---- ----
zmq_flush - flushes pre-sent messages to the socket zmq_flush - flush messages queued on a socket
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_flush (void *s);' *int zmq_flush (void '*socket');*
DESCRIPTION DESCRIPTION
----------- -----------
Flushes all the pre-sent messages - i.e. those that have been sent with The _zmq_flush()_ function shall flush messages previously queued on the socket
ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in referenced by the 'socket' argument. The _zmq_flush()_ function only affects
cases where several messages are sent during a single business operation. messages that have been queued on the _message queue_ associated with 'socket'
It should not be used as a transaction - ACID properties are not guaranteed. using the 'ZMQ_NOFLUSH' flag to the _zmq_send()_ function. If no such messages
Note that calling 'zmq_send' without ZMQ_NOFLUSH flag automatically flushes all exist, the function has no effect.
previously pre-sent messages.
CAUTION: A successful invocation of _zmq_flush()_ does not indicate that the
flushed messages have been transmitted to the network, or even that such a
transmission has been initiated by 0MQ. This function exists merely as a way
for the application programmer to supply a hint to the 0MQ infrastructure that
the queued messages *may* be flushed as a single batch.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_flush()_ function shall return zero if successful. Otherwise it shall
sets 'errno' to the appropriate value. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*ENOTSUP*:: *ENOTSUP*::
function isn't supported by particular socket type. The _zmq_flush()_ operation is not supported by this socket type.
*EFSM*:: *EFSM*::
function cannot be called at the moment, because socket is not in the The _zmq_flush()_ operation cannot be performed on this socket at the moment
approprite state. due to the socket not being in the appropriate state.
EXAMPLE
-------
----
rc = zmq_send (s, &msg1, ZMQ_NOFLUSH);
assert (rc == 0);
rc = zmq_send (s, &msg2, ZMQ_NOFLUSH);
assert (rc == 0);
rc = zmq_flush (s);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_send[3] linkzmq:zmq_send[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
AUTHOR AUTHOR
------ ------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_forwarder.txt
View file @ 1aee8640
...@@ -4,29 +4,30 @@ zmq_forwarder(1) ...@@ -4,29 +4,30 @@ zmq_forwarder(1)
NAME NAME
---- ----
zmq_forwarder - forwards the stream of PUB/SUB messages zmq_forwarder - forwarding device for publish-subscribe messaging
SYNOPSIS SYNOPSIS
-------- --------
* To be written.
DESCRIPTION DESCRIPTION
----------- -----------
* To be written.
OPTIONS OPTIONS
------- -------
* To be written.
SEE ALSO SEE ALSO
-------- --------
* linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_init.txt
View file @ 1aee8640
...@@ -4,58 +4,56 @@ zmq_init(3) ...@@ -4,58 +4,56 @@ zmq_init(3)
NAME NAME
---- ----
zmq_init - initialises 0MQ context zmq_init - initialise 0MQ context
SYNOPSIS SYNOPSIS
-------- --------
'void *zmq_init (int app_threads, int io_threads, int flags);' *void *zmq_init (int 'app_threads', int 'io_threads', int 'flags');*
DESCRIPTION DESCRIPTION
----------- -----------
Initialises 0MQ context. 'app_threads' specifies maximal number of application The _zmq_init()_ function initialises a 0MQ 'context' with 'app_threads'
threads that can own open sockets at the same time. At least one application application threads and 'io_threads' I/O threads.
thread should be defined. 'io_threads' specifies the size of thread pool to
handle I/O operations. The value shouldn't be negative. Zero can be used in The 'app_threads' argument specifies the maximum number of application threads
case only in-process messaging is going to be used, i.e. there will be no I/O that will be using 0MQ sockets in this 'context'. As a guide, set this to the
traffic. number of threads in your application.
The 'io_threads' argument specifies the size of the 0MQ thread pool to handle
I/O operations. If your application is using 'inproc' messaging exclusively you
may set this to zero, otherwise set it to at least one.
The 'flags' argument is a combination of the flags defined below: The 'flags' argument is a combination of the flags defined below:
*ZMQ_POLL*:: *ZMQ_POLL*::
flag specifying that the sockets within this context should be pollable Specifies that sockets within this 'context' should support multiplexing using
(see linkzmq:zmq_poll[3]). Pollable sockets may add a little latency to the _zmq_poll()_. Enabling this functionality may add a small amount of latency to
message transfer when compared to non-pollable sockets. message transfers compared to leaving it disabled.
RETURN VALUE RETURN VALUE
------------ ------------
Function returns context handle is successful. Otherwise it returns NULL and The _zmq_init()_ function shall return an opaque handle to the initialised
sets errno to one of the values below. 'context' if successful. Otherwise it shall return NULL and set 'errno' to one
of the values defined below.
ERRORS ERRORS
------ ------
*EINVAL*:: *EINVAL*::
there's less than one application thread allocated, or number of I/O The number of 'app_threads' requested is less than one, or the number of
threads is negative. 'io_threads' requested is negative.
EXAMPLE
-------
----
void *ctx = zmq_init (1, 1, ZMQ_POLL);
assert (ctx);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq[7]
linkzmq:zmq_term[3] linkzmq:zmq_term[3]
linkzmq:zmq_socket[3]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_inproc.txt
View file @ 1aee8640
...@@ -4,47 +4,86 @@ zmq_inproc(7) ...@@ -4,47 +4,86 @@ zmq_inproc(7)
NAME NAME
---- ----
zmq_inproc - 0MQ transport to pass messages between threads zmq_inproc - 0MQ local in-process (inter-thread) communication transport
SYNOPSIS SYNOPSIS
-------- --------
In-process transport is optimised for passing messages between threads in the The in-process transport passes messages via memory directly between threads
same process. sharing a single 0MQ 'context'.
Messages are passed directly from one application thread to NOTE: No I/O threads are involved in passing messages using the 'inproc'
another application thread. There are no intervening I/O threads involved. transport. Therefore, if you are using a 0MQ 'context' for in-process messaging
Thus, if you are using 0MQ for in-process messaging only, you can initialise only you can initialise the 'context' with zero I/O threads. See
the library (linkzmq:zmq_init[3]) with zero I/O worker threads. linkzmq:zmq_init[3] for details.
CONNECTION STRING ADDRESSING
----------------- ----------
Connection string for inproc transport is "inproc://" followed by an arbitrary A 0MQ address string consists of two parts as follows:
string. There are no restrictions on the string format: 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use, and for the in-process transport shall be set to
`inproc`. The meaning of the 'endpoint' part for the in-process transport 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'.
----
inproc://my_endpoint Connecting a socket
inproc://feeds/opra/cboe ~~~~~~~~~~~~~~~~~~~
inproc://feeds.opra.nasdaq When connecting a 'socket' to a peer address using _zmq_connect()_ with the
inproc://!&W#($)_@_123*((^^^ 'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
---- identifying the 'name' to connect to. The 'name' must have been previously
created by assigning it to at least one 'socket' within the same 0MQ 'context'
as the 'socket' being connected.
WIRE FORMAT WIRE FORMAT
----------- -----------
In-process transport transfers messages via memory thus there is no need for a Not applicable.
wire format specification.
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 SEE ALSO
-------- --------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_ipc[7] linkzmq:zmq_ipc[7]
linkzmq:zmq_tcp[7] linkzmq:zmq_tcp[7]
linkzmq:zmq_udp[7]
linkzmq:zmq_pgm[7] linkzmq:zmq_pgm[7]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_ipc.txt
View file @ 1aee8640
...@@ -4,41 +4,77 @@ zmq_ipc(7) ...@@ -4,41 +4,77 @@ zmq_ipc(7)
NAME NAME
---- ----
zmq_ipc - 0MQ transport to pass messages between processes zmq_ipc - 0MQ local inter-process communication transport
SYNOPSIS SYNOPSIS
-------- --------
Inter-process transport is optimised for passing messages between processes on The inter-process transport passes messages between local processes using a
the same physical machine. system-dependent IPC mechanism.
NOTE: The inter-process transport is currently only implemented on operating
systems that provide UNIX domain sockets.
CONNECTION STRING
-----------------
Connection string for inter-process transport is "ipc://" followed by a file
name. The file will be used as placeholder for a message endpoint. (UNIX domain
sockets associate a file with the listening socket in a similar way.)
---- ADDRESSING
ipc:///tmp/my_ipc_endpoint ----------
ipc:///tmp/prices.ipc A 0MQ address string consists of two parts as follows:
---- 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use, and for the inter-process transport shall be set to
`ipc`. The meaning of the 'endpoint' part for the inter-process transport is
defined below.
Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a 'socket' 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'.
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()_.
WIRE FORMAT WIRE FORMAT
----------- -----------
IPC transport doesn't transfer messages across the network thus there is no need Not applicable.
for a wire format specification.
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 SEE ALSO
-------- --------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_inproc[7] linkzmq:zmq_inproc[7]
linkzmq:zmq_tcp[7] linkzmq:zmq_tcp[7]
linkzmq:zmq_udp[7]
linkzmq:zmq_pgm[7] linkzmq:zmq_pgm[7]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_java.txt deleted 100644 → 0
View file @ d790940f
zmq_java(7)
===========
NAME
----
zmq_java - interface between 0MQ and Java applications
SYNOPSIS
--------
*
DESCRIPTION
-----------
*
SEE ALSO
--------
*
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
doc/zmq_msg_close.txt
View file @ 1aee8640
...@@ -4,25 +4,33 @@ zmq_msg_close(3) ...@@ -4,25 +4,33 @@ zmq_msg_close(3)
NAME NAME
---- ----
zmq_msg_close - destroys 0MQ message zmq_msg_close - release 0MQ message
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_msg_close (zmq_msg_t *msg);' *int zmq_msg_close (zmq_msg_t '*msg');*
DESCRIPTION DESCRIPTION
----------- -----------
Deallocates message 'msg' including any associated buffers (unless the buffer The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any
is shared with another message). Not calling this function can result in resources associated with the message object referenced by 'msg' are no longer
memory leaks. 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.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and sets The _zmq_msg_close()_ function shall return zero if successful. Otherwise
'errno' to the appropriate value. it shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -30,24 +38,17 @@ ERRORS ...@@ -30,24 +38,17 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 1000000);
assert (rc = 0);
rc = zmq_msg_close (&msg);
assert (rc = 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_copy.txt
View file @ 1aee8640
...@@ -4,30 +4,35 @@ zmq_msg_copy(3) ...@@ -4,30 +4,35 @@ zmq_msg_copy(3)
NAME NAME
---- ----
zmq_msg_copy - copies content of a message to another message zmq_msg_copy - copy content of a message to another message
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);' *int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION DESCRIPTION
----------- -----------
Copy the 'src' message to 'dest'. The original content of The _zmq_msg_copy()_ function shall copy the message object referenced by 'src'
'dest' is orderly deallocated. to the message object referenced by 'dest'. The original content of 'dest', if
any, shall be released.
CAUTION: The implementation may choose not to physically copy the data, rather CAUTION: The implementation may choose not to physically copy the message
to share the buffer between two messages. Thus avoid modifying message data content, rather to share the underlying buffer between 'src' and 'dest'. Avoid
after the message was copied. Doing so can modify multiple message instances. modifying message content after a message has been copied with
If what you need is actual hard copy, allocate new message using _zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need
'zmq_msg_size' and copy the data using 'memcpy'. is an actual hard copy, allocate a new message using _zmq_msg_init_size()_ and
copy the message content using _memcpy()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it
sets 'errno' to the appropriate value. shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -35,17 +40,6 @@ ERRORS ...@@ -35,17 +40,6 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
zmq_msg_t dest;
rc = zmq_msg_init (&dest);
assert (rc == 0);
rc = zmq_msg_copy (&dest, &src);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_move[3] linkzmq:zmq_msg_move[3]
...@@ -53,8 +47,10 @@ linkzmq:zmq_msg_init[3] ...@@ -53,8 +47,10 @@ linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_data.txt
View file @ 1aee8640
...@@ -4,23 +4,27 @@ zmq_msg_data(3) ...@@ -4,23 +4,27 @@ zmq_msg_data(3)
NAME NAME
---- ----
zmq_msg_data - retrieves pointer to the message content zmq_msg_data - retrieve pointer to message content
SYNOPSIS SYNOPSIS
-------- --------
'void *zmq_msg_data (zmq_msg_t *msg);' *void *zmq_msg_data (zmq_msg_t '*msg');*
DESCRIPTION DESCRIPTION
----------- -----------
Returns pointer to message data. Always use this function to access the data, The _zmq_msg_data()_ function shall return a pointer to the message content of
never use 'zmq_msg_t' members directly. 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 RETURN VALUE
------------ ------------
Pointer to the message data. Upon successful completion, _zmq_msg_data()_ shall return a pointer to the
message content.
ERRORS ERRORS
...@@ -28,23 +32,17 @@ ERRORS ...@@ -28,23 +32,17 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 100);
memset (zmq_msg_data (&msg), 0, 100);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_init.txt
View file @ 1aee8640
...@@ -4,24 +4,28 @@ zmq_msg_init(3) ...@@ -4,24 +4,28 @@ zmq_msg_init(3)
NAME NAME
---- ----
zmq_msg_init - initialises empty 0MQ message zmq_msg_init - initialise empty 0MQ message
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_msg_init (zmq_msg_t *msg);' *int zmq_msg_init (zmq_msg_t '*msg');*
DESCRIPTION DESCRIPTION
----------- -----------
Initialises 0MQ message zero bytes long. The function is most useful The _zmq_msg_init()_ function shall initialise the message object referenced by
to initialise a 'zmq_msg_t' structure before receiving a message. 'msg' to represent an empty message. This function is most useful when called
before receiving a message with _zmq_recv()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_msg_init()_ function shall return zero if successful. Otherwise it
sets 'errno' to the appropriate value. shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -31,24 +35,27 @@ No errors are defined. ...@@ -31,24 +35,27 @@ No errors are defined.
EXAMPLE EXAMPLE
------- -------
.Receiving a message from a socket
---- ----
zmq_msg_t msg; zmq_msg_t msg;
rc = zmq_msg_init (&msg); rc = zmq_msg_init (&msg);
assert (rc == 0); assert (rc == 0);
rc = zmq_recv (s, &msg, 0); rc = zmq_recv (socket, &msg, 0);
assert (rc == 0); assert (rc == 0);
---- ----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3] linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_init_data.txt
View file @ 1aee8640
...@@ -4,30 +4,35 @@ zmq_msg_init_data(3) ...@@ -4,30 +4,35 @@ zmq_msg_init_data(3)
NAME NAME
---- ----
zmq_msg_init_data - initialises 0MQ message from the given data zmq_msg_init_data - initialise 0MQ message from a supplied buffer
SYNOPSIS SYNOPSIS
-------- --------
'typedef void (zmq_free_fn) (void *data, void *hint);' *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);'
*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
DESCRIPTION DESCRIPTION
----------- -----------
Initialise a message from a supplied buffer. Message isn't copied, The _zmq_msg_init_data()_ function shall initialise the message object
instead 0MQ infrastructure takes ownership of the buffer located at address referenced by 'msg' to represent the content referenced by the buffer located
'data', 'size' bytes long. Deallocation function ('ffn') will be called once at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
the data are not needed anymore. When using a static constant buffer, 'ffn' may 0MQ shall take ownership of the supplied buffer.
be NULL to prevent subsequent deallocation. If needed, additional 'hint' can be
passed to the initialisation function. It's an opaque pointer that will be If provided, the deallocation function 'ffn' shall be called once the data
later on passed to 'ffn' as a second argument. 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.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
sets 'errno' to the appropriate value. it shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -37,10 +42,14 @@ No errors are defined. ...@@ -37,10 +42,14 @@ No errors are defined.
EXAMPLE EXAMPLE
------- -------
.Initialising a message from a supplied buffer
---- ----
void my_free (void *data, void *hint) {free (data);} void my_free (void *data, void *hint)
{
free (data);
}
... /* ... */
void *data = malloc (6); void *data = malloc (6);
assert (data); assert (data);
...@@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6); ...@@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6);
zmq_msg_t msg; zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL); rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0); assert (rc == 0);
rc = zmq_send (s, &msg, 0);
assert (rc == 0);
---- ----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[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_data[3]
linkzmq:zmq_msg_size[3] linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_init_size.txt
View file @ 1aee8640
...@@ -4,58 +4,51 @@ zmq_msg_init_size(3) ...@@ -4,58 +4,51 @@ zmq_msg_init_size(3)
NAME NAME
---- ----
zmq_msg_init_size - initialises 0MQ message of a specified size zmq_msg_init_size - initialise 0MQ message of a specified size
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_msg_init_size (zmq_msg_t *msg, size_t size);' *int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
DESCRIPTION DESCRIPTION
----------- -----------
Initialises 0MQ message 'size' bytes long. The implementation chooses whether The _zmq_msg_init_size()_ function shall allocate any resources required to
it is more efficient to store message content on the stack (small messages) or store a message 'size' bytes long and initialise the message object referenced
on the heap (large messages). Therefore, never access message data directly by 'msg' to represent the newly allocated message.
via 'zmq_msg_t' members, rather use 'zmq_msg_data' and 'zmq_msg_size' functions
to get message data and size. Note that the message data are not nullified to The implementation shall choose whether to store message content on the stack
avoid the associated performance impact. Thus you should expect your message to (small messages) or on the heap (large messages). For performance reasons
contain bogus data after this call. _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.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
sets 'errno' to the appropriate value. it shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*ENOMEM*:: *ENOMEM*::
memory to hold the message cannot be allocated. Insufficient storage space is available.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
memcpy (zmq_msg_data (&msg), "ABCDEF", 6);
rc = zmq_send (s, &msg, 0);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3] linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_move.txt
View file @ 1aee8640
...@@ -4,25 +4,30 @@ zmq_msg_move(3) ...@@ -4,25 +4,30 @@ zmq_msg_move(3)
NAME NAME
---- ----
zmq_msg_move - moves content of a message to another message zmq_msg_move - move content of a message to another message
SYNOPSIS SYNOPSIS
-------- --------
int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src); *int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION DESCRIPTION
----------- -----------
Move the content of the message from 'src' to 'dest'. The content isn't The _zmq_msg_move()_ function shall move the content of the message object
copied, just moved. 'src' becomes an empty message after the call. Original referenced by 'src' to the message object referenced by 'dest'. No actual
content of 'dest' message is deallocated. 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 RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
sets 'errno' to the appropriate value. shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -30,17 +35,6 @@ ERRORS ...@@ -30,17 +35,6 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
zmq_msg_t dest;
rc = zmq_msg_init (&dest);
assert (rc == 0);
rc = zmq_msg_move (&dest, &src);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_copy[3] linkzmq:zmq_msg_copy[3]
...@@ -48,8 +42,10 @@ linkzmq:zmq_msg_init[3] ...@@ -48,8 +42,10 @@ linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_msg_size.txt
View file @ 1aee8640
...@@ -4,23 +4,27 @@ zmq_msg_size(3) ...@@ -4,23 +4,27 @@ zmq_msg_size(3)
NAME NAME
---- ----
zmq_msg_size - retrieves size of the message content zmq_msg_size - retrieve message content size in bytes
SYNOPSIS SYNOPSIS
-------- --------
'size_t zmq_msg_size (zmq_msg_t *msg);' *size_t zmq_msg_size (zmq_msg_t '*msg');*
DESCRIPTION DESCRIPTION
----------- -----------
Returns size of the message data. Always use this function to get the size, The _zmq_msg_size()_ function shall return the size in bytes of the content of
never use 'zmq_msg_t' members directly. 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 RETURN VALUE
------------ ------------
Size of the message data (bytes). Upon successful completion, _zmq_msg_data()_ shall return the size of the
message content in bytes.
ERRORS ERRORS
...@@ -28,26 +32,17 @@ ERRORS ...@@ -28,26 +32,17 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init (&msg);
assert (rc == 0);
rc = zmq_recv (s, &msg, 0);
assert (rc == 0);
size_t msg_size = zmq_msg_size (&msg);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_pgm.txt
View file @ 1aee8640
...@@ -4,103 +4,125 @@ zmq_pgm(7) ...@@ -4,103 +4,125 @@ zmq_pgm(7)
NAME NAME
---- ----
zmq_pgm - 0MQ PGM reliable multicast transport zmq_pgm - 0MQ reliable multicast transport using PGM
SYNOPSIS SYNOPSIS
-------- --------
PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows PGM (Pragmatic General Multicast) is a protocol for reliable multicast
you to deliver messages to multiple destinations sending the data over transport of data over IP networks.
the network once only. It makes sense to use PGM transport if the data,
delivered to each destination separately, would seriously load or even overload
the network.
PGM sending is rate limited rather than controlled by receivers. Thus, to get
optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options
prior to using PGM transport. Also note that passing multicast packets via
loopback interface has negative effect on the overall performance of the system.
Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP
socket option.
PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets.
CAUTION: PGM protocol runs directly on top of IP protocol and thus needs to
open raw IP socket. On some operating systems this operation requires special
privileges. On Linux, for example, you would need to either run your application
as root or set adequate capabilities for your executable. Alternative approach
is to use UDP transport, linkzmq:zmq_udp[7], that stacks PGM on top of UDP and
thus needs no special privileges.
CONNECTION STRING
-----------------
Connection string for PGM transport is "pgm://" followed by an IP address
of the NIC to use, semicolon, IP address of the multicast group, colon and
port number. IP address of the NIC can be either its numeric representation
or the name of the NIC as reported by operating system. IP address of the
multicast group should be specified in the numeric representation. For example:
----
pgm://eth0;224.0.0.1:5555
pgm://lo;230.0.0.0:6666
pgm://192.168.0.111;224.0.0.1:5555
----
NOTE: NIC names are not standardised by POSIX. They tend to be rather arbitrary DESCRIPTION
and platform dependent. Say, "eth0" on Linux would correspond to "en0" on OSX -----------
and "e1000g" on Solaris. On Windows platform, as there are no short NIC names 0MQ implements two variants of PGM, the standard protocol where PGM datagrams
available, you have to use numeric IP addresses instead. are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
transport) and "Encapsulated PGM" 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.
WIRE FORMAT Further, PGM sockets are rate limited by default and incur a performance
----------- penalty when used over a loopback interface. For details, refer to the
Consecutive PGM packets are interpreted as a single continuous stream of data. 'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in
The data is then split into messages using the wire format described in linkzmq:zmq_setsockopt[3].
linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and
each message can start at an arbitrary position within the packet and span
several packets.
Given this wire format, it would be impossible for late joining consumers to CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
identify message boundaries. To solve this problem, each PGM packet payload Additional privileges may be required on some operating systems for this
starts with 16-bit unsigned integer in network byte order which specifies the operation. Applications not requiring direct interoperability with other PGM
offset of the first message in the packet. If there's no beginning of a message implementations are encouraged to use the 'epgm' transport instead which does
in the packet (it's a packet transferring inner part of a larger message) not require any special privileges.
the value of the initial integer is 0xFFFF.
Each packet thus looks like this:
---- ADDRESSING
+-----------+------------+------------------+-------- ----------
| IP header | PGM header | offset (16 bits) | data ..... A 0MQ address string consists of two parts as follows:
+-----------+------------+------------------+-------- 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
---- transport protocol to use. For the standard PGM protocol, 'transport' shall be
set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to
`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm'
transport is defined below.
Following example shows how messages are arranged in subsequent packets:
---- Connecting a socket
+---------------+--------+-----------+-----------------------------+ ~~~~~~~~~~~~~~~~~~~
| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) | 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.
| PGM/IPheaders | 0xFFFF | message 2 (part 2) | * The primary IPv4 address assigned to the interface, in it's numeric
+---------------+--------+-----------------------------------------+ representation.
+---------------+--------+--------------------------+-----------+ NOTE: Interface names are not standardised in any way and should be assumed to
| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 | 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'.
A 'multicast address' is specified by an IPv4 multicast address in it's numeric
representation.
WIRE FORMAT
-----------
Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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].
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.
A single PGM datagram as used by 0MQ can thus be defined by the following ABNF
grammar:
....
datagram = message / intermediate
message = (frame-offset *data 1*frame) <1>
intermediate = (escape 1*data)
frame-offset = 2OCTET
escape = %xFF %xFF
data = 1*OCTET
....
<1> 'frame' as defined in linkzmq:zmq_tcp[7].
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 SEE ALSO
-------- --------
linkzmq:zmq_udp[7] linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7] linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7] linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7] linkzmq:zmq_inproc[7]
linkzmq:zmq_setsockopt[3] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_poll.txt
View file @ 1aee8640
...@@ -4,83 +4,127 @@ zmq_poll(3) ...@@ -4,83 +4,127 @@ zmq_poll(3)
NAME NAME
---- ----
zmq_poll - polls for events on a set of 0MQ and POSIX sockets zmq_poll - input/output multiplexing
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);'
*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
DESCRIPTION DESCRIPTION
----------- -----------
Waits for the events specified by 'items' parameter. Number of items in the The _zmq_poll()_ function provides a mechanism for applications to multiplex
array is determined by 'nitems' argument. Each item in the array looks like input/output events in a level-triggered fashion over a set of sockets. Each
this: 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 typedef struct
{ {
void *socket; void '*socket';
int fd; int 'fd';
short events; short 'events';
short revents; short 'revents';
} zmq_pollitem_t; } zmq_pollitem_t;
----
0MQ socket to poll on is specified by 'socket'. In case you want to poll on For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
standard POSIX socket, set 'socket' to NULL and fill the POSIX file descriptor socket referenced by 'socket' *or* the standard socket specified by the file
to 'fd'. 'events' specifies which events to wait for. It's a combination of descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
the values below. Once the call exits, 'revents' will be filled with events 'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
that have actually occured on the socket. The field will contain a combination 'socket' shall take precedence and the value of 'fd' shall be ignored.
of the values below.
For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
member, and then indicate any requested events that have occured by setting the
bit corresponding to the event condition in the 'revents' member.
If none of the requested events have occured on any *zmq_pollitem_t* item,
_zmq_poll()_ shall wait up to 'timeout' microseconds 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 wait
indefinitely for requested events to occur.
The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed
by OR'ing a combination of the following event flags:
*ZMQ_POLLIN*:: *ZMQ_POLLIN*::
poll for incoming messages. For 0MQ sockets, at least one message may be dequeued from the underlying
_message queue_ associated with '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*:: *ZMQ_POLLOUT*::
wait while message can be set socket. Poll will return if a message of at least For 0MQ sockets, at least one message may be queued on the underlying
one byte can be written to the socket. However, there is no guarantee that _message queue_ associated with 'socket' without blocking. For standard sockets
arbitrarily large message can be sent. 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()_.
'timeout' argument specifies an upper limit on the time for which 'zmq_poll' NOTE: The _zmq_poll()_ function may be implemented or emulated using operating
will block, in microseconds. Specifying a negative value in timeout means an system interfaces other than _poll()_, and as such may be subject to the limits
infinite timeout. of those interfaces in ways not defined in this documentation.
RETURN VALUE RETURN VALUE
------------ ------------
Function returns number of items signaled, 0 in the case of timeout or -1 Upon successful completion, the _zmq_poll()_ function shall return the number
in the case of error. of *zmq_pollitem_t* structures with events signaled in 'revents' or 0 if the
'timeout' period has expired and no events have been signaled. Upon failure,
_zmq_poll()_ shall return -1 and set 'errno' to one of the values defined
below.
ERRORS ERRORS
------ ------
*EFAULT*:: *EFAULT*::
there's a 0MQ socket in the pollset belonging to a different application thread. At least one of the members of the 'items' array refers to a 'socket' belonging
to a different application thread.
*ENOTSUP*:: *ENOTSUP*::
0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled. At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was initialised without the 'ZMQ_POLL' flag.
EXAMPLE EXAMPLE
------- -------
.Polling idenfinitely for input events on both a 0MQ socket and a standard socket.
---- ----
zmq_pollitem_t items [2]; zmq_pollitem_t items [2];
items [0].socket = s; /* First item refers to 0MQ socket 'socket' */
items [0].events = ZMQ_POLLIN; items[0].socket = socket;
items [1].socket = NULL; items[0].events = ZMQ_POLLIN;
items [1].fd = my_fd; /* Second item refers to standard socket 'fd' */
items [1].events = ZMQ_POLLIN; items[1].socket = NULL;
items[1].fd = fd;
int rc = zmq_poll (items, 2); items[1].events = ZMQ_POLLIN;
assert (rc != -1); /* Poll for events indefinitely */
int rc = zmq_poll (items, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in items[].revents */
---- ----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_socket[3] linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
Your operating system documentation for the _poll()_ system call.
AUTHOR
------ AUTHORS
Martin Sustrik <sustrik at 250bpm dot com> -------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_queue.txt
View file @ 1aee8640
...@@ -4,29 +4,30 @@ zmq_queue(1) ...@@ -4,29 +4,30 @@ zmq_queue(1)
NAME NAME
---- ----
zmq_queue - forwards REQ/REP messages zmq_queue - forwarding device for request-reply messaging
SYNOPSIS SYNOPSIS
-------- --------
* To be written.
DESCRIPTION DESCRIPTION
----------- -----------
* To be written.
OPTIONS OPTIONS
------- -------
* To be written.
SEE ALSO SEE ALSO
-------- --------
* linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_recv.txt
View file @ 1aee8640
...@@ -4,51 +4,60 @@ zmq_recv(3) ...@@ -4,51 +4,60 @@ zmq_recv(3)
NAME NAME
---- ----
zmq_recv - retrieves a message from the socket zmq_recv - receive a message from a socket
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_recv (void *s, zmq_msg_t *msg, int flags);' *int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION DESCRIPTION
----------- -----------
Receive a message from the socket 's', store it in The _zmq_recv()_ function shall dequeue a message from the underlying _message
'msg' . Any content previously in 'msg' will be properly deallocated. 'flags' queue_ associated with the socket referenced by the 'socket' argument and store
argument can be combination of the flags described below. it in the message referenced by the 'msg' argument. Any content previously
stored in 'msg' shall be properly deallocated. If there are no messages
available to be dequeued from the underlying _message queue_ associated with
'socket' the _zmq_recv()_ function shall block until the request can be
satisfied. The 'flags' argument is a combination of the flags defined below:
*ZMQ_NOBLOCK*:: *ZMQ_NOBLOCK*::
The flag specifies that the operation should be performed in Specifies that the operation should be performed in non-blocking mode. If there
non-blocking mode. I.e. if it cannot be processed immediately, are no messages available to be dequeued from the underlying _message queue_
error should be returned with 'errno' set to EAGAIN. associated with 'socket', the _zmq_recv()_ function shall fail with 'errno' set
to EAGAIN.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
sets 'errno' to the appropriate value. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*EAGAIN*:: *EAGAIN*::
it's a non-blocking receive and there's no message available at the moment. Non-blocking mode was requested and no messages are available at the moment.
*ENOTSUP*:: *ENOTSUP*::
function isn't supported by particular socket type. The _zmq_recv()_ operation is not supported by this socket type.
*EFSM*:: *EFSM*::
function cannot be called at the moment, because socket is not in the The _zmq_recv()_ operation cannot be performed on this socket at the moment due
appropriate state. This error may occur with sockets that switch between to the socket not being in the appropriate state. This error may occur with
several states (e.g. ZMQ_REQ). socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
EXAMPLE EXAMPLE
------- -------
.Receiving a message from a socket
---- ----
/* Create an empty 0MQ message */
zmq_msg_t msg; zmq_msg_t msg;
int rc = zmq_msg_init (&msg); int rc = zmq_msg_init (&msg);
assert (rc == 0); assert (rc == 0);
rc = zmq_recv (s, &msg, 0); /* Block until a message is available to be dequeued from socket */
rc = zmq_recv (socket, &msg, 0);
assert (rc == 0); assert (rc == 0);
---- ----
...@@ -56,11 +65,11 @@ assert (rc == 0); ...@@ -56,11 +65,11 @@ assert (rc == 0);
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_send[3] linkzmq:zmq_send[3]
linkzmq:zmq_msg_init[3] linkzmq:zmq_socket[7]
linkzmq:zmq_msg_data[3] linkzmq:zmq[7]
linkzmq:zmq_msg_size[3]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_send.txt
View file @ 1aee8640
...@@ -4,59 +4,69 @@ zmq_send(3) ...@@ -4,59 +4,69 @@ zmq_send(3)
NAME NAME
---- ----
zmq_send - sends a message zmq_send - send a message on a socket
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_send (void *s, zmq_msg_t *msg, int flags);' *int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION DESCRIPTION
----------- -----------
Send the message 'msg' to the socket 's'. 'flags' argument can be combination The _zmq_send()_ function shall queue the message referenced by the 'msg'
the flags described below. argument to be sent to the socket referenced by the 'socket' argument. The
'flags' argument is a combination of the flags defined below:
*ZMQ_NOBLOCK*:: *ZMQ_NOBLOCK*::
The flag specifies that the operation should be performed in non-blocking mode. Specifies that the operation should be performed in non-blocking mode. If the
I.e. if it cannot be processed immediately, error should be returned with message cannot be queued on the underlying _message queue_ associated with
'errno' set to EAGAIN. 'socket', the _zmq_send()_ function shall fail with 'errno' set to EAGAIN.
*ZMQ_NOFLUSH*:: *ZMQ_NOFLUSH*::
The flag specifies that 'zmq_send' should not flush the message downstream Specifies that the _zmq_send()_ function should not flush the underlying
immediately. Instead, it should batch ZMQ_NOFLUSH messages and send them _message queue_ associated with 'socket' to the network automatically.
downstream only once 'zmq_flush' is invoked. This is an optimisation for cases Instead, it should batch all messages queued with the 'ZMQ_NOFLUSH' flag and
where several messages are sent in a single business transaction. However, the only flush the _message queue_ once either a message without the 'ZMQ_NOFLUSH'
effect is measurable only in extremely high-perf scenarios (million messages a flag is queued, or manually on invocation of the _zmq_flush()_ function.
second or so). If that's not your case, use standard flushing send instead.
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 _message queue_ associated with the socket and 0MQ has assumed
responsibility for the message.
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_send()_ function shall return zero if successful. Otherwise it shall
sets 'errno' to the appropriate value. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*EAGAIN*:: *EAGAIN*::
it's a non-blocking send and message cannot be sent at the moment. Non-blocking mode was requested and the message cannot be queued at the moment.
*ENOTSUP*:: *ENOTSUP*::
function isn't supported by particular socket type. The _zmq_send()_ operation is not supported by this socket type.
*EFSM*:: *EFSM*::
function cannot be called at the moment, because socket is not in the The _zmq_send()_ operation cannot be performed on this socket at the moment due
appropriate state. This error may occur with sockets that switch between to the socket not being in the appropriate state. This error may occur with
several states (e.g. ZMQ_REQ). socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
EXAMPLE 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; zmq_msg_t msg;
int rc = zmq_msg_init_size (&msg, 6); int rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0); assert (rc == 0);
/* Fill in message content with 'AAAAAA' */
memset (zmq_msg_data (&msg), 'A', 6); memset (zmq_msg_data (&msg), 'A', 6);
rc = zmq_send (s, &msg, 0); /* Send the message to the socket */
rc = zmq_send (socket, &msg, 0);
assert (rc == 0); assert (rc == 0);
---- ----
...@@ -65,13 +75,11 @@ SEE ALSO ...@@ -65,13 +75,11 @@ SEE ALSO
-------- --------
linkzmq:zmq_flush[3] linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3] linkzmq:zmq_recv[3]
linkzmq:zmq_msg_init[3] linkzmq:zmq_socket[7]
linkzmq:zmq_msg_init_size[3] linkzmq:zmq[7]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_setsockopt.txt
View file @ 1aee8640
...@@ -5,144 +5,255 @@ zmq_setsockopt(3) ...@@ -5,144 +5,255 @@ zmq_setsockopt(3)
NAME NAME
---- ----
zmq_setsockopt - sets a specified option on a 0MQ socket zmq_setsockopt - set 0MQ socket options
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);' *int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
DESCRIPTION DESCRIPTION
----------- -----------
Sets an option on the socket. 'option' argument specifies the option from the The _zmq_setsockopt()_ function shall set the option specified by the
list below. 'optval' is a pointer to the value to set, 'optvallen' is the size 'option_name' argument to the value pointed to by the 'option_value' argument
of the value in bytes. for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
argument is the size of the option value in bytes.
*ZMQ_HWM*::
High watermark for the message pipes associated with the socket. The water The following options are defined:
mark cannot be exceeded. If the messages don't fit into the pipe emergency
mechanisms of the particular socket type are used (block, drop etc.) If HWM
is set to zero, there are no limits for the content of the pipe. ZMQ_HWM: Set high water mark
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Type: int64_t Unit: messages Default: 0 The 'ZMQ_HWM' option shall set the high water mark for the _message queue_
associated with the socket. The high water mark is a hard limit on the number
*ZMQ_LWM*:: of outstanding messages in the queue; if this limit has been reached the socket
Low watermark makes sense only if high watermark is defined (i.e. is non-zero). shall enter an "emergency" state and depending on the socket type, 0MQ shall
When the emergency state is reached when messages overflow the pipe, the take appropriate action such as blocking or dropping new messages entering the
emergency lasts at most till the size of the pipe decreases to low watermark. queue.
Normal state is resumed at that point.
+ The default 'ZMQ_HWM' value of zero means "no limit".
Type: int64_t Unit: messages Default: 0
Option value type:: int64_t
*ZMQ_SWAP*:: Option value unit:: messages
Swap allows the pipe to exceed high watermark. However, the data are written Default value:: 0
to the disk rather than held in the memory. Until high watermark is Applicable socket types:: all
exceeded there is no disk activity involved though. The value of the option
defines maximal size of the swap file.
+ ZMQ_LWM: Set low water mark
Type: int64_t Unit: bytes Default: 0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_LWM' option shall set the low water mark for the _message queue_
*ZMQ_AFFINITY*:: associated with the socket. This option only makes sense when used in
Affinity defines which threads in the thread pool will be used to handle conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high
newly created sockets. This way you can dedicate some of the threads (CPUs) water mark remains in the "emergency" state until the number of outstanding
to a specific work. Value of 0 means no affinity. Work is distributed messages in it's associated message queue falls below the low water mark, at
fairly among the threads in the thread pool. For non-zero values, the lowest which point normal message processing is resumed.
bit corresponds to the thread 1, second lowest bit to the thread 2 etc.
Thus, value of 3 means that from now on newly created sockets will handle Option value type:: int64_t
I/O activity exclusively using threads no. 1 and 2. Option value unit:: messages
+ Default value:: 0
Type: int64_t Unit: N/A (bitmap) Default: 0 Applicable socket types:: all
*ZMQ_IDENTITY*::
Identity of the socket. Identity is important when restarting applications. ZMQ_SWAP: Set disk offload size
If the socket has no identity, each run of the application is completely ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
separated from other runs. However, with identity application reconnects to The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the _message
existing infrastructure left by the previous run. Thus it may receive queue_ associated with the socket. A socket which has 'ZMQ_SWAP' set to a
messages that were sent in the meantime, it shares pipe limits with the non-zero value may exceed it's high water mark; in this case outstanding
previous run etc. Identity should be at least one byte and at most 255 bytes messages shall be offloaded to storage on disk rather than held in memory.
long. Identities starting with binary zero are reserver for use by 0MQ
infrastructure. The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
+
Type: BLOB Unit: N/A Default: NULL Option value type:: int64_t
Option value unit:: bytes
*ZMQ_SUBSCRIBE*:: Default value:: 0
Applicable only to ZMQ_SUB socket type. It establishes new message filter. Applicable socket types:: all
When ZMQ_SUB socket is created all the incoming messages are filtered out.
This option allows you to subscribe for all messages (""), or messages
beginning with specific prefix (e.g. "animals.mammals.dogs."). Multiple ZMQ_AFFINITY: Set I/O thread affinity
filters can be attached to a single 'sub' socket. In that case message passes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
if it matches at least one of the filters. The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections
+ created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified
Type: BLOB Unit: N/A Default: N/A 'socket'.
*ZMQ_UNSUBSCRIBE*:: sockets. Affinity determines which threads from the 0MQ I/O thread pool
Applicable only to ZMQ_SUB socket type. Removes existing message filter. associated with the socket's _context_ shall handle newly created connections.
The filter specified must match the string passed to ZMQ_SUBSCRIBE options A value of zero specifies no affinity, meaning that work shall be distributed
exactly. If there were several instances of the same filter created, fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the
this options removes only one of them, leaving the rest in place lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on.
and functional. For example, a value of 3 specifies that subsequent connections on 'socket'
+ shall be handled exclusively by I/O threads 1 and 2.
Type: BLOB Unit: N/A Default: N/A
See also linkzmq:zmq_init[3] for details on allocating the number of I/O
*ZMQ_RATE*:: threads for a specific _context_.
This option applies only to sending side of multicast transports (pgm & udp).
It specifies maximal outgoing data rate that an individual sender socket Option value type:: int64_t
can send. Option value unit:: N/A (bitmap)
+ Default value:: 0
Type: uint64_t Unit: kilobits/second Default: 100 Applicable socket types:: N/A
*ZMQ_RECOVERY_IVL*::
This option applies only to multicast transports (pgm & udp). It specifies ZMQ_IDENTITY: Set socket identity
how long can the receiver socket survive when the sender is inaccessible. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Keep in mind that large recovery intervals at high data rates result in The 'ZMQ_IDENTITY' option shall set the identity of the socket. Socket identity
very large recovery buffers, meaning that you can easily overload your box determines if existing 0MQ infastructure (_message queues_, _forwarding
by setting say 1 minute recovery interval at 1Gb/s rate (requires devices_) shall be identified with a specific application and persist across
7GB in-memory buffer). multiple runs of the application.
+
Type: uint64_t Unit: seconds Default: 10 If the socket has no identity, each run of an application is completely
separate from other runs. However, with identity set the socket shall re-use
*ZMQ_MCAST_LOOP*:: any existing 0MQ infrastructure configured by the previous run(s). Thus the
This option applies only to multicast transports (pgm & udp). Value of 1 application may receive messages that were sent in the meantime, _message
means that the mutlicast packets can be received on the box they were sent queue_ limits shall be shared with previous run(s) and so on.
from. Setting the value to 0 disables the loopback functionality which
can have negative impact on the performance. If possible, disable Identity should be at least one byte and at most 255 bytes long. Identities
the loopback in production environments. starting with binary zero are reserved for use by 0MQ infrastructure.
+
Type: uint64_t Unit: N/A (boolean value) Default: 1 Option value type:: BLOB
Option value unit:: N/A
*ZMQ_SNDBUF*:: Default value:: NULL
Sets the underlying kernel transmit buffer size to the specified size. See Applicable socket types:: all
'SO_SNDBUF' POSIX socket option. Value of zero means leaving the OS default
unchanged.
+ ZMQ_SUBSCRIBE: Establish message filter
Type: uint64_t Unit: bytes Default: 0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB'
*ZMQ_RCVBUF*:: socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages,
Sets the underlying kernel receive buffer size to the specified size. See therefore you should call this option to establish an initial message filter.
'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default
unchanged. An empty 'option_value' of length zero shall subscribe to all incoming
+ messages. A non-empty 'option_value' shall subscribe to all messages beginning
Type: uint64_t Unit: bytes Default: 0 with the specified prefix. Mutiple filters may be attached to a single
'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at
least one filter.
Option value type:: BLOB
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB
ZMQ_UNSUBSCRIBE: Remove message filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a
'ZMQ_SUB' socket. The filter specified must match an existing filter previously
established with the 'ZMQ_SUBSCRIBE' option. If the socket has several
instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove
only one instance, leaving the rest in place and functional.
Option value type:: BLOB
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB
ZMQ_RATE: Set multicast data rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
multicast transports such as linkzmq:zmq_pgm[7] and linkzmq:zmq_udp[7] using
the specified 'socket'.
Option value type:: uint64_t
Option value unit:: kilobits per second
Default value:: 100
Applicable socket types:: all, when using multicast transports
ZMQ_RECOVERY_IVL: Set multicast recovery interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast
transports such as linkzmq:zmq_pgm[7] and linkzmq:zmq_udp[7] using the
specified 'socket'. The recovery interval determines the maximum time in
seconds that a receiver can be absent from a multicast group before
unrecoverable data loss will occur.
CAUTION: Excersize care when setting large recovery intervals as the data
needed for recovery will be held in memory. For example, a 1 minute recovery
interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
Option value type:: uint64_t
Option value unit:: seconds
Default value:: 10
Applicable socket types:: all, when using multicast transports
ZMQ_MCAST_LOOP: Control multicast loopback
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast
transports can also be received by the sending host via loopback. A value of
zero disables the loopback functionality, while the default value of 1 enables
the loopback functionality. Leaving multicast loopback enabled when it is not
required can have a negative impact on performance. Where possible, disable
'ZMQ_MCAST_LOOP' in production environments.
Option value type:: uint64_t
Option value unit:: boolean
Default value:: 1
Applicable socket types:: all, when using multicast transports
ZMQ_SNDBUF: Set kernel transmit buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size
for the socket to the specified size in bytes. A value of zero means leave the
OS default unchanged. For details please refer to your operating system
documentation for the 'SO_SNDBUF' socket option.
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 0
Applicable socket types:: all
ZMQ_RCVBUF: Set kernel receive buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for
the socket to the specified size in bytes. A value of zero means leave the OS
default unchanged. For details refer to your operating system documentation for
the 'SO_RCVBUF' socket option.
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 0
Applicable socket types:: all
RETURN VALUE RETURN VALUE
------------ ------------
In case of success the function returns zero. Otherwise it returns -1 and The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
sets 'errno' to the appropriate value. shall return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
------ ------
*EINVAL*:: *EINVAL*::
unknown option, a value with incorrect length or invalid value. The requested option _option_name_ is unknown, or the requested _option_len_ or
_option_value_ is invalid.
EXAMPLE EXAMPLE
------- -------
.Subscribing to messages on a 'ZMQ_SUB' socket
---- ----
int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "", 0); /* Subscribe to all messages */
rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
assert (rc == 0); assert (rc == 0);
/* Subscribe to messages prefixed with "ANIMALS.CATS" */
rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
----
.Setting I/O thread affinity
----
/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 1, sizeof (int64_t));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5555");
assert (rc);
/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 2, sizeof (int64_t));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5555");
assert (rc);
---- ----
...@@ -152,6 +263,7 @@ linkzmq:zmq_socket[3] ...@@ -152,6 +263,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_socket.txt
View file @ 1aee8640
...@@ -4,110 +4,117 @@ zmq_socket(3) ...@@ -4,110 +4,117 @@ zmq_socket(3)
NAME NAME
---- ----
zmq_socket - creates 0MQ socket zmq_socket - create 0MQ socket
SYNOPSIS SYNOPSIS
-------- --------
'void *zmq_socket (void *context, int type);' *void *zmq_socket (void '*context', int 'type');*
DESCRIPTION DESCRIPTION
----------- -----------
Open a socket within the specified 'context'. To create a context, use The 'zmq_socket()' function shall create a 0MQ socket within the specified
'zmq_init' function. 'type' argument can be one of the values defined below. 'context' and return an opaque handle to the newly created socket. The 'type'
Note that each socket is owned by exactly one thread (the one that it was argument specifies the _messaging pattern_, which determines the semantics of
created from) and should not be used from any other thread. communication over the socket.
*ZMQ_P2P*:: The following _messaging patterns_ are defined:
Socket to communicate with a single peer. Allows for only a single connect
or a single bind. There's no message routing or message filtering involved.
+ Peer to peer pattern
Compatible peer sockets: ZMQ_P2P. ~~~~~~~~~~~~~~~~~~~~
The simplest messaging pattern, used for communicating between two peers.
*ZMQ_PUB*::
Socket to distribute data. Recv function is not implemented for this socket Socket type:: 'ZMQ_P2P'
type. Messages are distributed in fanout fashion to all the peers. Compatible peer sockets:: 'ZMQ_P2P'
+
Compatible peer sockets: ZMQ_SUB. A socket of type 'ZMQ_P2P' 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_SUB*:: 'ZMQ_P2P' socket.
Socket to subscribe for data. Send function is not implemented for this socket
type. Initially, socket is subscribed for no messages. Use ZMQ_SUBSCRIBE option
to specify which messages to subscribe for. Publish-subscribe pattern
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
Compatible peer sockets: ZMQ_PUB. The publish-subscribe pattern is used for one-to-many distribution of data from
a single _publisher_ to multiple _subscribers_ in a fanout fashion.
*ZMQ_REQ*::
Socket to send requests and receive replies. Requests are load-balanced among Socket type:: 'ZMQ_PUB'
all the peers. This socket type allows only an alternated sequence of send's Compatible peer sockets:: 'ZMQ_SUB'
and recv's.
+ A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
Compatible peer sockets: ZMQ_REP, ZMQ_XREP. Messages sent are distributed in a fanout fashion to all connected peers.
The _zmq_recv()_ function is not implemented for this socket type.
*ZMQ_REP*::
Socket to receive requests and send replies. This socket type allows only an Socket type:: 'ZMQ_SUB'
alternated sequence of recv's and send's. Each send is routed to the peer that Compatible peer sockets:: 'ZMQ_PUB'
issued the last received request.
+ A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ. distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify
*ZMQ_XREQ*:: which messages to subscribe to. The _zmq_send()_ function is not implemented
Special socket type to be used in request/reply middleboxes such as for this socket type.
linkzmq:zmq_queue[7]. Requests forwarded using this socket type should be
tagged by a proper prefix identifying the original requester. Replies received
by this socket are tagged with a proper prefix that can be use to route the Request-reply pattern
reply back to the original requester. ~~~~~~~~~~~~~~~~~~~~~
+ The request-reply pattern is used for sending requests from a _client_ to a
Compatible peer sockets: ZMQ_REP, ZMQ_XREP. _service_, and receiving subsequent replies to each request sent.
*ZMQ_XREP*:: Socket type:: 'ZMQ_REQ'
Special socket type to be used in request/reply middleboxes such as Compatible peer sockets:: 'ZMQ_REP'
linkzmq:zmq_queue[7]. Requests received using this socket are already properly
tagged with prefix identifying the original requester. When sending a reply via A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
XREP socket the message should be tagged with a prefix from a corresponding receive replies from a _service_. This socket type allows only an alternating
request. sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
+ request sent is load-balanced among all connected _services_.
Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
Socket type:: 'ZMQ_REP'
*ZMQ_UPSTREAM*:: Compatible peer sockets:: 'ZMQ_REQ'
Socket to receive messages from up the stream. Messages are fair-queued from
among all the connected peers. Send function is not implemented for this socket A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
type. send replies to a _client_. This socket type allows only an alternating
+ sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
Compatible peer sockets: ZMQ_DOWNSTREAM. reply is routed to the _client_ that issued the last received request.
*ZMQ_DOWNSTREAM*::
Socket to send messages down stream. Messages are load-balanced among all the Parallelized pipeline pattern
connected peers. Recv function is not implemented for this socket type. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ The parallelized pipeline pattern is used for distributing work between
Compatible peer sockets: ZMQ_UPSTREAM. _components_ of a pipeline. Work travels down the pipeline and at each stage
can be processed by any number of _components_ in parallel.
Socket type:: 'ZMQ_UPSTREAM'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to
receive messages from upstream stages of the pipeline. Messages are fair-queued
from among all connected upstream _components_. The _zmq_send()_ function is
not implemented for this socket type.
Socket type:: 'ZMQ_DOWNSTREAM'
Compatible peer sockets:: 'ZMQ_UPSTREAM'
A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
send messages to downstream stages of the pipeline. The _zmq_recv()_ function
is not implemented for this socket type.
RETURN VALUE RETURN VALUE
------------ ------------
Function returns socket handle is successful. Otherwise it returns NULL and The _zmq_socket()_ function shall return an opaque handle to the newly created
sets errno to one of the values below. socket if successful. Otherwise, it shall return NULL and set 'errno' to one of
the values defined below.
ERRORS ERRORS
------ ------
*EINVAL*:: *EINVAL*::
invalid socket type. The requested socket 'type' is invalid.
*EMTHREAD*:: *EMTHREAD*::
the number of application threads allowed to own 0MQ sockets was exceeded. The number of application threads using sockets within this 'context' has been
See 'app_threads' parameter to 'zmq_init' function. exceeded. See the 'app_threads' parameter of the _zmq_init()_ function.
EXAMPLE
-------
----
void *s = zmq_socket (context, ZMQ_PUB);
assert (s);
int rc = zmq_bind (s, "tcp://192.168.0.1:5555");
assert (rc == 0);
----
SEE ALSO SEE ALSO
...@@ -121,6 +128,7 @@ linkzmq:zmq_flush[3] ...@@ -121,6 +128,7 @@ linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3] linkzmq:zmq_recv[3]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_streamer.txt
View file @ 1aee8640
...@@ -4,29 +4,30 @@ zmq_streamer(1) ...@@ -4,29 +4,30 @@ zmq_streamer(1)
NAME NAME
---- ----
zmq_streamer - forwards the stream of UPSTREAM/DOWNSTREAM messages zmq_streamer - streamer device for parallelized pipeline messaging
SYNOPSIS SYNOPSIS
-------- --------
* To be written.
DESCRIPTION DESCRIPTION
----------- -----------
* To be written.
OPTIONS OPTIONS
------- -------
* To be written.
SEE ALSO SEE ALSO
-------- --------
* linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_strerror.txt
View file @ 1aee8640
...@@ -4,24 +4,27 @@ zmq_strerror(3) ...@@ -4,24 +4,27 @@ zmq_strerror(3)
NAME NAME
---- ----
zmq_strerror - returns string describing the error number zmq_strerror - get 0MQ error message string
SYNOPSIS SYNOPSIS
-------- --------
'const char *zmq_strerror (int errnum);' *const char *zmq_strerror (int 'errnum');*
DESCRIPTION DESCRIPTION
----------- -----------
As 0MQ defines few additional (non-POSIX) error codes, standard The _zmq_strerror()_ function shall return a pointer to an error message string
'strerror' isn't capable of translating those errors into human readable corresponding to the error number specified by the 'errnum' argument. As 0MQ
strings. Instead, 'zmq_strerror' should be used. 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 RETURN VALUE
------------ ------------
Returns string describing the error number. The _zmq_strerror()_ function shall return a pointer to an error message
string.
ERRORS ERRORS
...@@ -31,10 +34,11 @@ No errors are defined. ...@@ -31,10 +34,11 @@ No errors are defined.
EXAMPLE EXAMPLE
------- -------
.Displaying an error message when a 0MQ context cannot be initialised
---- ----
void *ctx = zmq_init (1, 1, 0); void *ctx = zmq_init (1, 1, 0);
if (!ctx) { if (!ctx) {
printf ("error occured during zmq_init: %s\\n", zmq_strerror (errno)); printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
abort (); abort ();
} }
---- ----
...@@ -45,6 +49,7 @@ SEE ALSO ...@@ -45,6 +49,7 @@ SEE ALSO
linkzmq:zmq[7] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_tcp.txt
View file @ 1aee8640
...@@ -4,55 +4,72 @@ zmq_tcp(7) ...@@ -4,55 +4,72 @@ zmq_tcp(7)
NAME NAME
---- ----
zmq_tcp - 0MQ unicast TCP transport over the network zmq_tcp - 0MQ unicast transport using TCP
SYNOPSIS SYNOPSIS
-------- --------
TCP is an ubiquitous unicast transport. When connecting distributed TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
applications, you will mostly use TCP transport. applications over a network with 0MQ, using the TCP transport will likely be
your first choice.
CONNECTION STRING ADDRESSING
----------------- ----------
Connection string for TCP transport is "tcp://" followed by an IP address, A 0MQ address string consists of two parts as follows:
colon and port number. IP address can be either its numeric representation, 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
a NIC name or a hostname (resolved by DNS): transport protocol to use, and for the TCP transport shall be set to `tcp`.
The meaning of the 'endpoint' part for the TCP transport is defined below.
----
tcp://192.168.0.111:5555
tcp://myserver001:80
tcp://lo:32768
----
Note that NIC names are not standardised by POSIX. They tend to be rather Assigning a local address to a socket
arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
names available, you have to use numeric IP addresses instead. 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:
WIRE FORMAT * The interface name as defined by the operating system.
----------- * The primary IPv4 address assigned to the interface, in it's numeric representation.
A message consists of a message length followed by message data. * The wildcard `*`, meaning that the interface address is unspecified.
Size of message data MUST correspond to the message length.
For messages of 0 to 254 octets, the length is represented by single octet. 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'.
For messages of 255 or more octets the length is represented by a single octet Connecting a socket
%xFF followed by a 64-bit unsigned integer length in network byte order. ~~~~~~~~~~~~~~~~~~~
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.
The protocol can be defined by this BNF grammar: A 'peer address' may be specified by either of the following:
---- * The DNS name of the peer.
frame = length data * The IPv4 address of the peer, in it's numeric representation.
length = OCTET | escape 8*OCTET
escape = %xFF
data = *OCTET
----
Binary layout of a message (up to 254 bytes long):
---- WIRE FORMAT
-----------
0MQ messages are transmitted over TCP in frames consisting of the message
length followed by the message data. The size of the message data MUST
correspond to the message length. A single 'frame' can be defined by the
following ABNF grammar:
....
frame = (message-length message-data)
message-length = OCTET / (escape 8OCTET)
escape = %xFF
message-data = *OCTET
....
For messages of 0 to 254 octets in length, the message length is represented by
a single octet:
....
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...@@ -60,11 +77,13 @@ Binary layout of a message (up to 254 bytes long): ...@@ -60,11 +77,13 @@ Binary layout of a message (up to 254 bytes long):
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message body ... | Message body ...
+-+-+-+-+-+-+- ... +-+-+-+-+-+-+- ...
---- ....
Binary layout of a larger message: For messages of 255 or more octets in length, the message length is represented
by a single octet with the value `255` followed by the message length
represented as a 64-bit unsigned integer in network byte order:
---- ....
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...@@ -76,18 +95,46 @@ Binary layout of a larger message: ...@@ -76,18 +95,46 @@ Binary layout of a larger message:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message body ... | Message body ...
+-+-+-+-+-+-+-+ ... +-+-+-+-+-+-+-+ ...
....
EXAMPLES
--------
.Assigning a local address to a socket
----
/* TCP port 5555 on the local loopback 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);
/* TCP port 5555 with an unspecified interface */
rc = zmq_bind(socket, "tcp://*: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);
---- ----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq_udp[7] linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_pgm[7] linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7] linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7] linkzmq:zmq_inproc[7]
linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_term.txt
View file @ 1aee8640
...@@ -4,25 +4,27 @@ zmq_term(3) ...@@ -4,25 +4,27 @@ zmq_term(3)
NAME NAME
---- ----
zmq_term - terminates 0MQ context zmq_term - terminate 0MQ context
SYNOPSIS SYNOPSIS
-------- --------
'int zmq_term (void *context);' *int zmq_term (void '*context');*
DESCRIPTION DESCRIPTION
----------- -----------
Destroys 0MQ context. However, if there are still any sockets open within The _zmq_term()_ function terminates the 0MQ context 'context'.
the context, 'zmq_term' succeeds but shutdown of the context is delayed till
the last socket is closed. If there are still sockets open within 'context' at the time _zmq_term()_ is
called the call will succeed but the actual shutdown of 'context' will be
delayed until the last socket within it is closed.
RETURN VALUE RETURN VALUE
------------ ------------
Function returns zero is successful. Otherwise it returns -1 and sets errno to The _zmq_term()_ function shall return zero if successful. Otherwise it shall
one of the values below. return -1 and set 'errno' to one of the values defined below.
ERRORS ERRORS
...@@ -30,20 +32,13 @@ ERRORS ...@@ -30,20 +32,13 @@ ERRORS
No errors are defined. No errors are defined.
EXAMPLE
-------
----
int rc = zmq_term (context);
assert (rc == 0);
----
SEE ALSO SEE ALSO
-------- --------
linkzmq:zmq[7]
linkzmq:zmq_init[3] linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
doc/zmq_udp.txt deleted 100644 → 0
View file @ d790940f
zmq_udp(7)
==========
NAME
----
zmq_udp - 0MQ reliable multicast transport using UDP
SYNOPSIS
--------
UDP transport is exactly the same as PGM transport except that PGM packets
are encapsulated in UDP packets. Rationale for this transport is that user-space
implementation of PGM requires right to create raw sockets (PGM is located
directly on top of IP layer in the networking stack), which is often not
available. UDP encapsulation solves this problem, however, it adds some overhead
related to creating and transferring UDP packet headers.
CONNECTION STRING
-----------------
Connection string for UDP transport is "udp://" followed by an IP address
of the NIC to use, semicolon, IP address of the multicast group, colon and
port number. IP address of the NIC can be either its numeric representation
or the name of the NIC as reported by operating system. IP address of the
multicast group should be specified in the numeric representation. For example:
----
udp://eth0;224.0.0.1:5555
udp://lo;230.0.0.0:6666
udp://192.168.0.111;224.0.0.1:5555
----
NOTE: NIC names are not standardised by POSIX. They tend to be rather
arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0"
on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC
names available, you have to use numeric IP addresses instead.
WIRE FORMAT
-----------
Same as with PGM transport except for UDP packet headers.
SEE ALSO
--------
linkzmq:zmq_pgm[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
doc/zmq_version.txt
View file @ 1aee8640
...@@ -4,19 +4,24 @@ zmq_version(3) ...@@ -4,19 +4,24 @@ zmq_version(3)
NAME NAME
---- ----
zmq_version - reports 0MQ version zmq_version - report 0MQ library version
SYNOPSIS SYNOPSIS
-------- --------
'void zmq_version (int *major, int *minor, int *patch);' *void zmq_version (int '*major', int '*minor', int '*patch');*
DESCRIPTION DESCRIPTION
----------- -----------
Returns current version of 0MQ. The functionality is useful for applications The _zmq_version()_ function shall fill in the integer variables pointed to by
linking with 0MQ dynamically to make sure the right version of 0MQ is installed the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
on the system. 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 RETURN VALUE
------------ ------------
...@@ -30,6 +35,7 @@ No errors are defined. ...@@ -30,6 +35,7 @@ No errors are defined.
EXAMPLE EXAMPLE
------- -------
.Printing out the version of the 0MQ library
---- ----
int major, minor, patch; int major, minor, patch;
zmq_version (&major, &minor, &patch); zmq_version (&major, &minor, &patch);
...@@ -41,6 +47,7 @@ SEE ALSO ...@@ -41,6 +47,7 @@ SEE ALSO
-------- --------
linkzmq:zmq[7] linkzmq:zmq[7]
AUTHOR AUTHORS
------ -------
Martin Sustrik <sustrik at 250bpm dot com> The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment