diff options
34 files changed, 1297 insertions, 973 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 1158243..5a4e3ea 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.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 \ - zmq_cpp.7 zmq_java.7 +MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \ + zmq_cpp.7 MAN_DOC = $(MAN1) $(MAN3) $(MAN7) MAN_TXT = $(MAN1:%.1=%.txt) diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 18273f2..15633a3 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -1,3 +1,6 @@ +[paradef-default] +literal-style=template="literalparagraph" + [macros] (?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= @@ -32,3 +35,8 @@ template::[header-declarations] </refnamediv> endif::backend-docbook[] endif::doctype-manpage[] + +[replacements] +ifdef::backend-xhtml11[] +0MQ=ØMQ +endif::backend-xhtml11[] diff --git a/doc/zmq.txt b/doc/zmq.txt index bc2571b..21722a7 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel SYNOPSIS -------- -0MQ is an extension of POSIX sockets. It is a library that augments standard -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. +*#include <zmq.h>* -0MQ is designed to be extremely fast. Expected end-to-end latencies for -messages passed over a LAN are in tens of microseconds. Expected -throughputs are to be measured in millions of messages per second. +*cc* ['flags'] 'files' *-lzmq* ['libraries'] -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 -microarchitectures. +DESCRIPTION +----------- +The 0MQ lightweight messaging kernel is a library which extends the standard +socket interfaces with features traditionally provided by specialised +_messaging middleware_ products. 0MQ sockets provide an abstraction of +asynchronous _message queues_, multiple _messaging patterns_, message +filtering (_subscriptions_), seamless access to multiple _transport protocols_ +and more. -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 -------- -Each 0MQ socket lives within a specific context. Creating and destroying -context is a counterpart of library initialisation/deinitialisation as used -elsewhere. Ability to create multiple contexts saves the day when an application -happens to link (indirectly and involuntarily) with several instances of 0MQ. +Context +~~~~~~~ +Before using any 0MQ library functions the caller must initialise a 0MQ +'context' using _zmq_init()_. The following functions are provided to handle +initialisation and termination of a 'context': Initialise 0MQ context:: linkzmq:zmq_init[3] -Uninitialise 0MQ context:: +Terminate 0MQ context:: linkzmq:zmq_term[3] -MESSAGES --------- -Message is a discrete unit of data passed between applications or components -of the same application. 0MQ message has no internal structure, it is an opaque -BLOB. When writing data to or reading data from the message, you are free to -use any of the many serialisation libraries available. Alternatively, you can -use your own serialisation code. The latter option is especially useful when -migrating legacy applications to 0MQ - there's no need to break existing -message formats. +Thread safety +^^^^^^^^^^^^^ +A 0MQ 'context' is thread safe and may be shared among as many application +threads as the application has requested using the _app_threads_ parameter to +_zmq_init()_, without any additional locking required on the part of the +caller. Each 0MQ socket belonging to a particular 'context' may only be used +by *the thread that created it* using _zmq_socket()_. + + +Multiple contexts +^^^^^^^^^^^^^^^^^ +Multiple 'contexts' may coexist within a single application. Thus, an +application can use 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:: linkzmq:zmq_msg_init[3] - linkzmq:zmq_msg_size[3] - linkzmq:zmq_msg_data[3] + linkzmq:zmq_msg_init_size[3] + linkzmq:zmq_msg_init_data[3] -Uninitialise a message:: +Release a message:: linkzmq:zmq_msg_close[3] Access message content:: @@ -73,10 +83,21 @@ Message manipulation:: linkzmq:zmq_msg_move[3] -SOCKETS -------- -0MQ sockets are very similar to POSIX sockets. See following manual pages to -understand them in depth. +Sockets +~~~~~~~ +Standard sockets present a _synchronous_ interface to either connection-mode +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:: linkzmq:zmq_socket[3] @@ -91,82 +112,108 @@ Establishing a message flow:: linkzmq:zmq_bind[3] linkzmq:zmq_connect[3] -Sending & receiving messages:: +Sending and receiving messages:: linkzmq:zmq_send[3] linkzmq:zmq_flush[3] linkzmq:zmq_recv[3] -MULTIPLEXING ------------- -0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX) -in an asynchronous manner. - -Poll for I/O events:: - linkzmq:zmq_poll[3] - +Input/output multiplexing +^^^^^^^^^^^^^^^^^^^^^^^^^ +0MQ provides a mechanism for applications to multiplex input/output events over +a set containing both 0MQ sockets and standard sockets. This mechanism mirrors +the standard _poll()_ system call, and is described in detail in +linkzmq:zmq_poll[3]. -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 ----------- -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: +The following transport mechanisms are provided: -TCP/IP transport:: +Unicast transport using TCP:: linkzmq:zmq_tcp[7] -UDP reliable multicast transport:: - linkzmq:zmq_udp[7] - -PGM reliable multicast transport:: +Reliable multicast transport using PGM:: linkzmq:zmq_pgm[7] -Inter-process transport:: +Local inter-process communication transport:: linkzmq:zmq_ipc[7] -In-process (inter-thread) transport:: +Local in-process (inter-thread) communication transport:: linkzmq:zmq_inproc[7] -DEVICES -------- -Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built -executables - devices - to serve as middle nodes in complex messaging -topologies. For detailed description of individual devices check following -manual pages: +Devices +~~~~~~~ +Apart from the 0MQ library the 0MQ distribution includes 'devices' which are +building blocks intended to serve as intermediate nodes in complex messaging +topologies. -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] -Streamer device for UPSTREAM/DOWNSTREAM messaging:: +Streamer device for parallelized pipeline messaging:: 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++$$:: - linkzmq:zmq_cpp[7] +C++ language binding +~~~~~~~~~~~~~~~~~~~~ +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 ------- -Martin Sustrik <sustrik at 250bpm dot com> + +AUTHORS +------- +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. diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index 391238a..6d83752 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -4,53 +4,66 @@ zmq_bind(3) NAME ---- -zmq_bind - binds the socket to the specified address +zmq_bind - assign a local address to a socket SYNOPSIS -------- -'int zmq_bind (void *s, const char *addr);' +*int zmq_bind (void '*socket', const char '*address');* DESCRIPTION ----------- -The function binds socket 's' to a particular transport. Actual semantics of the -command depend on the underlying transport mechanism, however, in cases where -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. +The _zmq_bind()_ function shall assign a local address specified by the +'address' argument to the socket referenced by the 'socket' argument. -Note that single socket can be bound (and connected) to -arbitrary number of peers using different transport mechanisms. +The 'address' argument is a string consisting of two parts as follows: +'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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_bind()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS ------ *EPROTONOSUPPORT*:: -unsupported protocol. +The requested 'transport' protocol is not supported. *ENOCOMPATPROTO*:: -protocol is not compatible with the socket type. +The requested 'transport' protocol is not compatible with the socket type. *EADDRINUSE*:: -the given address is already in use. +The given 'address' is already in use. *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 ------- +.Binding a publisher socket to an in-process and a TCP transport ---- -void *s = zmq_socket (context, ZMQ_PUB); -assert (s); -int rc = zmq_bind (s, "inproc://my_publisher"); +/* Create a ZMQ_PUB socket */ +void *socket = zmq_socket (context, ZMQ_PUB); +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); -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); ---- @@ -62,6 +75,7 @@ linkzmq:zmq_socket[3] linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt index 9964d36..55b10f4 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.txt @@ -4,28 +4,29 @@ zmq_close(3) NAME ---- -zmq_close - destroys 0MQ socket +zmq_close - close 0MQ socket SYNOPSIS -------- -'int zmq_close (void *s);' +*int zmq_close (void '*socket');* DESCRIPTION ----------- -Destroys 0MQ socket (one created using -'zmq_socket' function). All sockets have to be properly closed before the -application terminates, otherwise memory leaks will occur. Note that any -outbound messages that haven't been psuhed to the network yet and any inbound -messages that haven't been received by the application yet will be dropped on -the socket shutdown. +The _zmq_close()_ function shall destroy the socket referenced by the 'socket' +argument. All active connections on the socket shall be terminated and +resources associated with the socket shall be released. Any outstanding +messages sent with _zmq_send()_ but not yet physically sent to the network +shall be dropped. Likewise, any outstanding messages physically received from +the network but not yet received by the application with _zmq_recv()_ shall +also be dropped. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_close()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS @@ -33,20 +34,14 @@ ERRORS No errors are defined. -EXAMPLE -------- ----- -int rc = zmq_close (s); -assert (rc == 0); ----- - - SEE ALSO -------- linkzmq:zmq_socket[3] linkzmq:zmq_term[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index 375873d..e0dd9ca 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -4,49 +4,66 @@ zmq_connect(3) NAME ---- -zmq_connect - connect the socket to the specified peer +zmq_connect - connect a socket to a peer address SYNOPSIS -------- -'int zmq_connect (void *s, const char *addr);' +*int zmq_connect (void '*socket', const char '*address');* DESCRIPTION ----------- -The function connect socket 's' to the peer identified by 'addr'. Actual -semantics of the command depend on the underlying transport mechanism, -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. +The _zmq_connect()_ function shall connect the socket referenced by the +'socket' argument to a peer address specified by the 'address' argument. -Note that single socket can be connected (and bound) to -arbitrary number of peers using different transport mechanisms. +The 'address' argument is a string consisting of two parts as follows: +'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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_connect()_ function shall return zero if successful. Otherwise it +shall return -1 and set 'errno' to one of the values defined below. ERRORS ------ *EPROTONOSUPPORT*:: -unsupported protocol. +The requested 'transport' protocol is not supported. *ENOCOMPATPROTO*:: -protocol is not compatible with the socket type. +The requested 'transport' protocol is not compatible with the socket type. EXAMPLE ------- +.Connecting a subscriber socket to an in-process and a TCP transport ---- -void *s = zmq_socket (context, ZMQ_SUB); -assert (s); -int rc = zmq_connect (s, "inproc://my_publisher"); +/* Create a ZMQ_SUB socket */ +void *socket = zmq_socket (context, ZMQ_SUB); +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); -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); ---- @@ -58,6 +75,7 @@ linkzmq:zmq_socket[3] linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt new file mode 120000 index 0000000..4d58b1b --- /dev/null +++ b/doc/zmq_epgm.txt @@ -0,0 +1 @@ +zmq_pgm.txt
\ No newline at end of file diff --git a/doc/zmq_flush.txt b/doc/zmq_flush.txt index 3a2cd37..77f4452 100644 --- a/doc/zmq_flush.txt +++ b/doc/zmq_flush.txt @@ -4,56 +4,52 @@ zmq_flush(3) NAME ---- -zmq_flush - flushes pre-sent messages to the socket +zmq_flush - flush messages queued on a socket SYNOPSIS -------- -'int zmq_flush (void *s);' +*int zmq_flush (void '*socket');* DESCRIPTION ----------- -Flushes all the pre-sent messages - i.e. those that have been sent with -ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in -cases where several messages are sent during a single business operation. -It should not be used as a transaction - ACID properties are not guaranteed. -Note that calling 'zmq_send' without ZMQ_NOFLUSH flag automatically flushes all -previously pre-sent messages. +The _zmq_flush()_ function shall flush messages previously queued on the socket +referenced by the 'socket' argument. The _zmq_flush()_ function only affects +messages that have been queued on the _message queue_ associated with 'socket' +using the 'ZMQ_NOFLUSH' flag to the _zmq_send()_ function. If no such messages +exist, the function has no effect. + +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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_flush()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS ------ *ENOTSUP*:: -function isn't supported by particular socket type. +The _zmq_flush()_ operation is not supported by this socket type. *EFSM*:: -function cannot be called at the moment, because socket is not in the -approprite 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); ----- +The _zmq_flush()_ operation cannot be performed on this socket at the moment +due to the socket not being in the appropriate state. SEE ALSO -------- linkzmq:zmq_send[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] 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>. diff --git a/doc/zmq_forwarder.txt b/doc/zmq_forwarder.txt index 17d938b..b3325f2 100644 --- a/doc/zmq_forwarder.txt +++ b/doc/zmq_forwarder.txt @@ -4,29 +4,30 @@ zmq_forwarder(1) NAME ---- -zmq_forwarder - forwards the stream of PUB/SUB messages +zmq_forwarder - forwarding device for publish-subscribe messaging SYNOPSIS -------- -* +To be written. DESCRIPTION ----------- -* +To be written. OPTIONS ------- -* +To be written. SEE ALSO -------- -* +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt index 6683d27..9df3e67 100644 --- a/doc/zmq_init.txt +++ b/doc/zmq_init.txt @@ -4,58 +4,56 @@ zmq_init(3) NAME ---- -zmq_init - initialises 0MQ context +zmq_init - initialise 0MQ context SYNOPSIS -------- -'void *zmq_init (int app_threads, int io_threads, int flags);' +*void *zmq_init (int 'app_threads', int 'io_threads', int 'flags');* DESCRIPTION ----------- -Initialises 0MQ context. 'app_threads' specifies maximal number of application -threads that can own open sockets at the same time. At least one application -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 -case only in-process messaging is going to be used, i.e. there will be no I/O -traffic. +The _zmq_init()_ function initialises a 0MQ 'context' with 'app_threads' +application threads and 'io_threads' I/O threads. + +The 'app_threads' argument specifies the maximum number of application threads +that will be using 0MQ sockets in this 'context'. As a guide, set this to the +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: *ZMQ_POLL*:: - flag specifying that the sockets within this context should be pollable - (see linkzmq:zmq_poll[3]). Pollable sockets may add a little latency to the - message transfer when compared to non-pollable sockets. +Specifies that sockets within this 'context' should support multiplexing using +_zmq_poll()_. Enabling this functionality may add a small amount of latency to +message transfers compared to leaving it disabled. RETURN VALUE ------------ -Function returns context handle is successful. Otherwise it returns NULL and -sets errno to one of the values below. +The _zmq_init()_ function shall return an opaque handle to the initialised +'context' if successful. Otherwise it shall return NULL and set 'errno' to one +of the values defined below. ERRORS ------ *EINVAL*:: - there's less than one application thread allocated, or number of I/O - threads is negative. - - -EXAMPLE -------- ----- -void *ctx = zmq_init (1, 1, ZMQ_POLL); -assert (ctx); ----- +The number of 'app_threads' requested is less than one, or the number of +'io_threads' requested is negative. SEE ALSO -------- +linkzmq:zmq[7] linkzmq:zmq_term[3] -linkzmq:zmq_socket[3] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt index 7861201..2805f71 100644 --- a/doc/zmq_inproc.txt +++ b/doc/zmq_inproc.txt @@ -4,47 +4,86 @@ zmq_inproc(7) NAME ---- -zmq_inproc - 0MQ transport to pass messages between threads +zmq_inproc - 0MQ local in-process (inter-thread) communication transport SYNOPSIS -------- -In-process transport is optimised for passing messages between threads in the -same process. +The in-process transport passes messages via memory directly between threads +sharing a single 0MQ 'context'. -Messages are passed directly from one application thread to -another application thread. There are no intervening I/O threads involved. -Thus, if you are using 0MQ for in-process messaging only, you can initialise -the library (linkzmq:zmq_init[3]) with zero I/O worker threads. +NOTE: No I/O threads are involved in passing messages using the 'inproc' +transport. Therefore, if you are using a 0MQ 'context' for in-process messaging +only you can initialise the 'context' with zero I/O threads. See +linkzmq:zmq_init[3] for details. -CONNECTION STRING ------------------ -Connection string for inproc transport is "inproc://" followed by an arbitrary -string. There are no restrictions on the string format: +ADDRESSING +---------- +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 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 - inproc://feeds/opra/cboe - inproc://feeds.opra.nasdaq - inproc://!&W#($)_@_123*((^^^ ----- + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a 'socket' to a peer address using _zmq_connect()_ with the +'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string +identifying the 'name' to connect to. 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 ----------- -In-process transport transfers messages via memory thus there is no need for a -wire format specification. +Not applicable. + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the in-process name "#1" */ +rc = zmq_bind(socket, "inproc://#1"); +assert (rc == 0); +/* Assign the in-process name "my-endpoint" */ +rc = zmq_bind(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connect to the in-process name "#1" */ +rc = zmq_connect(socket, "inproc://#1"); +assert (rc == 0); +/* Connect to the in-process name "my-endpoint" */ +rc = zmq_connect(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- SEE ALSO -------- +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] linkzmq:zmq_ipc[7] linkzmq:zmq_tcp[7] -linkzmq:zmq_udp[7] linkzmq:zmq_pgm[7] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt index acce97a..81f6747 100644 --- a/doc/zmq_ipc.txt +++ b/doc/zmq_ipc.txt @@ -4,41 +4,77 @@ zmq_ipc(7) NAME ---- -zmq_ipc - 0MQ transport to pass messages between processes +zmq_ipc - 0MQ local inter-process communication transport SYNOPSIS -------- -Inter-process transport is optimised for passing messages between processes on -the same physical machine. +The inter-process transport passes messages between local processes using a +system-dependent IPC mechanism. +NOTE: The inter-process transport is currently only implemented on operating +systems that provide UNIX domain sockets. -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.) ----- - ipc:///tmp/my_ipc_endpoint - ipc:///tmp/prices.ipc ----- +ADDRESSING +---------- +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 ----------- -IPC transport doesn't transfer messages across the network thus there is no need -for a wire format specification. +Not applicable. + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the pathname "/tmp/feeds/0" */ +rc = zmq_bind(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connect to the pathname "/tmp/feeds/0" */ +rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +---- SEE ALSO -------- +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] linkzmq:zmq_inproc[7] linkzmq:zmq_tcp[7] -linkzmq:zmq_udp[7] linkzmq:zmq_pgm[7] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_java.txt b/doc/zmq_java.txt deleted file mode 100644 index c49e589..0000000 --- a/doc/zmq_java.txt +++ /dev/null @@ -1,27 +0,0 @@ -zmq_java(7) -=========== - - -NAME ----- -zmq_java - interface between 0MQ and Java applications - - -SYNOPSIS --------- -* - - -DESCRIPTION ------------ -* - - -SEE ALSO --------- -* - - -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt index 1b043a2..dcc42ff 100644 --- a/doc/zmq_msg_close.txt +++ b/doc/zmq_msg_close.txt @@ -4,25 +4,33 @@ zmq_msg_close(3) NAME ---- -zmq_msg_close - destroys 0MQ message +zmq_msg_close - release 0MQ message SYNOPSIS -------- -'int zmq_msg_close (zmq_msg_t *msg);' +*int zmq_msg_close (zmq_msg_t '*msg');* DESCRIPTION ----------- -Deallocates message 'msg' including any associated buffers (unless the buffer -is shared with another message). Not calling this function can result in -memory leaks. +The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any +resources associated with the message object referenced by 'msg' are no longer +required and may be released. Actual release of resources associated with the +message object shall be postponed by 0MQ until all users of the message or +underlying data buffer have indicated it is no longer required. + +Applications should ensure that _zmq_msg_close()_ is called once a message is +no longer required, otherwise memory leaks may occur. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and sets -'errno' to the appropriate value. +The _zmq_msg_close()_ function shall return zero if successful. Otherwise +it shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -30,24 +38,17 @@ ERRORS 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 -------- linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt index b31897a..78337ea 100644 --- a/doc/zmq_msg_copy.txt +++ b/doc/zmq_msg_copy.txt @@ -4,30 +4,35 @@ zmq_msg_copy(3) NAME ---- -zmq_msg_copy - copies content of a message to another message +zmq_msg_copy - copy content of a message to another message 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 ----------- -Copy the 'src' message to 'dest'. The original content of -'dest' is orderly deallocated. +The _zmq_msg_copy()_ function shall copy the message object referenced by 'src' +to the message object referenced by 'dest'. The original content of 'dest', if +any, shall be released. -CAUTION: The implementation may choose not to physically copy the data, rather -to share the buffer between two messages. Thus avoid modifying message data -after the message was copied. Doing so can modify multiple message instances. -If what you need is actual hard copy, allocate new message using -'zmq_msg_size' and copy the data using 'memcpy'. +CAUTION: The implementation may choose not to physically copy the message +content, rather to share the underlying buffer between 'src' and 'dest'. Avoid +modifying message content after a message has been copied with +_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need +is an actual hard copy, 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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it +shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -35,17 +40,6 @@ ERRORS 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 -------- linkzmq:zmq_msg_move[3] @@ -53,8 +47,10 @@ linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt index 45a99b1..dbf6612 100644 --- a/doc/zmq_msg_data.txt +++ b/doc/zmq_msg_data.txt @@ -4,23 +4,27 @@ zmq_msg_data(3) NAME ---- -zmq_msg_data - retrieves pointer to the message content +zmq_msg_data - retrieve pointer to message content SYNOPSIS -------- -'void *zmq_msg_data (zmq_msg_t *msg);' +*void *zmq_msg_data (zmq_msg_t '*msg');* DESCRIPTION ----------- -Returns pointer to message data. Always use this function to access the data, -never use 'zmq_msg_t' members directly. +The _zmq_msg_data()_ function shall return a pointer to the message content of +the message object referenced by 'msg'. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -Pointer to the message data. +Upon successful completion, _zmq_msg_data()_ shall return a pointer to the +message content. ERRORS @@ -28,23 +32,17 @@ ERRORS 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 -------- +linkzmq:zmq_msg_size[3] linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt index b080c18..904dc08 100644 --- a/doc/zmq_msg_init.txt +++ b/doc/zmq_msg_init.txt @@ -4,24 +4,28 @@ zmq_msg_init(3) NAME ---- -zmq_msg_init - initialises empty 0MQ message +zmq_msg_init - initialise empty 0MQ message SYNOPSIS -------- -'int zmq_msg_init (zmq_msg_t *msg);' +*int zmq_msg_init (zmq_msg_t '*msg');* DESCRIPTION ----------- -Initialises 0MQ message zero bytes long. The function is most useful -to initialise a 'zmq_msg_t' structure before receiving a message. +The _zmq_msg_init()_ function shall initialise the message object referenced by +'msg' to represent an empty message. This function is most useful when called +before receiving a message with _zmq_recv()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_init()_ function shall return zero if successful. Otherwise it +shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -31,24 +35,27 @@ No errors are defined. EXAMPLE ------- +.Receiving a message from a socket ---- zmq_msg_t msg; rc = zmq_msg_init (&msg); assert (rc == 0); -rc = zmq_recv (s, &msg, 0); +rc = zmq_recv (socket, &msg, 0); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt index 1ae6ce2..5adfeee 100644 --- a/doc/zmq_msg_init_data.txt +++ b/doc/zmq_msg_init_data.txt @@ -4,30 +4,35 @@ zmq_msg_init_data(3) NAME ---- -zmq_msg_init_data - initialises 0MQ message from the given data +zmq_msg_init_data - initialise 0MQ message from a supplied buffer SYNOPSIS -------- -'typedef void (zmq_free_fn) (void *data, void *hint);' -'int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, void *hint);' +*typedef void (zmq_free_fn) (void '*data', void '*hint');* + +*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');* DESCRIPTION ----------- -Initialise a message from a supplied buffer. Message isn't copied, -instead 0MQ infrastructure takes ownership of the buffer located at address -'data', 'size' bytes long. Deallocation function ('ffn') will be called once -the data are not needed anymore. When using a static constant buffer, 'ffn' may -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 -later on passed to 'ffn' as a second argument. +The _zmq_msg_init_data()_ function shall initialise the message object +referenced by 'msg' to represent the content referenced by the buffer located +at address 'data', 'size' bytes long. No copy of 'data' shall be performed and +0MQ shall take ownership of the supplied buffer. + +If provided, the deallocation function 'ffn' shall be called once the data +buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments +supplied to _zmq_msg_init_data()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise +it shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -37,10 +42,14 @@ No errors are defined. 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); assert (data); @@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6); zmq_msg_t msg; rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL); assert (rc == 0); -rc = zmq_send (s, &msg, 0); -assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt index 9f09ade..1217eb2 100644 --- a/doc/zmq_msg_init_size.txt +++ b/doc/zmq_msg_init_size.txt @@ -4,58 +4,51 @@ zmq_msg_init_size(3) NAME ---- -zmq_msg_init_size - initialises 0MQ message of a specified size +zmq_msg_init_size - initialise 0MQ message of a specified size 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 ----------- -Initialises 0MQ message 'size' bytes long. The implementation chooses whether -it is more efficient to store message content on the stack (small messages) or -on the heap (large messages). Therefore, never access message data directly -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 -avoid the associated performance impact. Thus you should expect your message to -contain bogus data after this call. +The _zmq_msg_init_size()_ function shall allocate any resources required to +store a message 'size' bytes long and initialise the message object referenced +by 'msg' to represent the newly allocated message. + +The implementation shall choose whether to store message content on the stack +(small messages) or on the heap (large messages). For performance reasons +_zmq_msg_init_size()_ shall not clear the message data. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise +it shall return -1 and set 'errno' to one of the values defined below. ERRORS ------ *ENOMEM*:: -memory to hold the message cannot be allocated. - - -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); ----- +Insufficient storage space is available. SEE ALSO -------- -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_init[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_size[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt index d8ce667..e8bde8a 100644 --- a/doc/zmq_msg_move.txt +++ b/doc/zmq_msg_move.txt @@ -4,25 +4,30 @@ zmq_msg_move(3) NAME ---- -zmq_msg_move - moves content of a message to another message +zmq_msg_move - move content of a message to another message 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 ----------- -Move the content of the message from 'src' to 'dest'. The content isn't -copied, just moved. 'src' becomes an empty message after the call. Original -content of 'dest' message is deallocated. +The _zmq_msg_move()_ function shall move the content of the message object +referenced by 'src' to the message object referenced by 'dest'. No actual +copying of message content is performed, 'dest' is simply updated to reference +the new content. 'src' becomes an empty message after calling _zmq_msg_move()_. +The original content of 'dest', if any, shall be released. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_move()_ function shall return zero if successful. Otherwise it +shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -30,17 +35,6 @@ ERRORS 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 -------- linkzmq:zmq_msg_copy[3] @@ -48,8 +42,10 @@ linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt index 6d24243..05abfa6 100644 --- a/doc/zmq_msg_size.txt +++ b/doc/zmq_msg_size.txt @@ -4,23 +4,27 @@ zmq_msg_size(3) NAME ---- -zmq_msg_size - retrieves size of the message content +zmq_msg_size - retrieve message content size in bytes SYNOPSIS -------- -'size_t zmq_msg_size (zmq_msg_t *msg);' +*size_t zmq_msg_size (zmq_msg_t '*msg');* DESCRIPTION ----------- -Returns size of the message data. Always use this function to get the size, -never use 'zmq_msg_t' members directly. +The _zmq_msg_size()_ function shall return the size in bytes of the content of +the message object referenced by 'msg'. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -Size of the message data (bytes). +Upon successful completion, _zmq_msg_data()_ shall return the size of the +message content in bytes. ERRORS @@ -28,26 +32,17 @@ ERRORS 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 -------- +linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index d0e2622..c92824e 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -4,103 +4,125 @@ zmq_pgm(7) NAME ---- -zmq_pgm - 0MQ PGM reliable multicast transport +zmq_pgm - 0MQ reliable multicast transport using PGM SYNOPSIS -------- -PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows -you to deliver messages to multiple destinations sending the data over -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 (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. ----- - 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 -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. +DESCRIPTION +----------- +0MQ implements two variants of PGM, the standard protocol where PGM datagrams +are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm' +transport) and "Encapsulated PGM" 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 ------------ -Consecutive PGM packets are interpreted as a single continuous stream of data. -The data is then split into messages using the wire format described in -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. +Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loopback interface. For details, refer to the +'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in +linkzmq:zmq_setsockopt[3]. -Given this wire format, it would be impossible for late joining consumers to -identify message boundaries. To solve this problem, each PGM packet payload -starts with 16-bit unsigned integer in network byte order which specifies the -offset of the first message in the packet. If there's no beginning of a message -in the packet (it's a packet transferring inner part of a larger message) -the value of the initial integer is 0xFFFF. +CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. +Additional privileges may be required on some operating systems for this +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the 'epgm' transport instead which does +not require any special privileges. -Each packet thus looks like this: ----- -+-----------+------------+------------------+-------- -| IP header | PGM header | offset (16 bits) | data ..... -+-----------+------------+------------------+-------- ----- +ADDRESSING +---------- +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: ----- -+---------------+--------+-----------+-----------------------------+ -| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) | -+---------------+--------+-----------+-----------------------------+ +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm' +or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface' +followed by a semicolon, followed by a 'multicast address', followed by a colon +and a port number. + +An 'interface' may be specified by either of the following: -+---------------+--------+-----------------------------------------+ -| PGM/IPheaders | 0xFFFF | message 2 (part 2) | -+---------------+--------+-----------------------------------------+ +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric + representation. -+---------------+--------+--------------------------+-----------+ -| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 | -+---------------+--------+--------------------------+-----------+ +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'. + +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 -------- -linkzmq:zmq_udp[7] +linkzmq:zmq_connect[3] +linkzmq:zmq_setsockopt[3] linkzmq:zmq_tcp[7] linkzmq:zmq_ipc[7] linkzmq:zmq_inproc[7] -linkzmq:zmq_setsockopt[3] - +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index 9969d0f..b654041 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -4,83 +4,127 @@ zmq_poll(3) NAME ---- -zmq_poll - polls for events on a set of 0MQ and POSIX sockets +zmq_poll - input/output multiplexing SYNOPSIS -------- -'int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);' + +*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');* DESCRIPTION ----------- -Waits for the events specified by 'items' parameter. Number of items in the -array is determined by 'nitems' argument. Each item in the array looks like -this: +The _zmq_poll()_ function provides a mechanism for applications to multiplex +input/output events in a level-triggered fashion over a set of sockets. Each +member of the array pointed to by the 'items' argument is a *zmq_pollitem_t* +structure. The 'nitems' argument specifies the number of items in the 'items' +array. The *zmq_pollitem_t* structure is defined as follows: ----- +["literal", subs="quotes"] typedef struct { - void *socket; - int fd; - short events; - short revents; + void '*socket'; + int 'fd'; + short 'events'; + short 'revents'; } zmq_pollitem_t; ----- -0MQ socket to poll on is specified by 'socket'. In case you want to poll on -standard POSIX socket, set 'socket' to NULL and fill the POSIX file descriptor -to 'fd'. 'events' specifies which events to wait for. It's a combination of -the values below. Once the call exits, 'revents' will be filled with events -that have actually occured on the socket. The field will contain a combination -of the values below. +For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ +socket referenced by 'socket' *or* the standard socket specified by the file +descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and +'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by +'socket' shall take precedence and the value of 'fd' shall be ignored. + +For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents' +member, and then indicate any requested events that have 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*:: -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*:: -wait while message can be set socket. Poll will return if a message of at least -one byte can be written to the socket. However, there is no guarantee that -arbitrarily large message can be sent. +For 0MQ sockets, at least one message may be queued on the underlying +_message queue_ associated with 'socket' without blocking. For standard sockets +this is equivalent to the 'POLLOUT' flag of the _poll()_ system call and +generally means that at least one byte of data may be written to 'fd' +without blocking. + +*ZMQ_POLLERR*:: +For standard sockets, this flag is passed through _zmq_poll()_ to the +underlying _poll()_ system call and generally means that some sort of error +condition is present on the socket specified by 'fd'. For 0MQ sockets this flag +has no effect if set in 'events', and shall never be returned in 'revents' by +_zmq_poll()_. -'timeout' argument specifies an upper limit on the time for which 'zmq_poll' -will block, in microseconds. Specifying a negative value in timeout means an -infinite timeout. +NOTE: The _zmq_poll()_ function may be implemented or emulated using operating +system interfaces other than _poll()_, and as such may be subject to the limits +of those interfaces in ways not defined in this documentation. RETURN VALUE ------------ -Function returns number of items signaled, 0 in the case of timeout or -1 -in the case of error. +Upon successful completion, the _zmq_poll()_ function shall return the number +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 ------ *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*:: -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 ------- +.Polling idenfinitely for input events on both a 0MQ socket and a standard socket. ---- zmq_pollitem_t items [2]; -items [0].socket = s; -items [0].events = ZMQ_POLLIN; -items [1].socket = NULL; -items [1].fd = my_fd; -items [1].events = ZMQ_POLLIN; - -int rc = zmq_poll (items, 2); -assert (rc != -1); +/* First item refers to 0MQ socket 'socket' */ +items[0].socket = socket; +items[0].events = ZMQ_POLLIN; +/* Second item refers to standard socket 'fd' */ +items[1].socket = NULL; +items[1].fd = fd; +items[1].events = ZMQ_POLLIN; +/* Poll for events indefinitely */ +int rc = zmq_poll (items, 2, -1); +assert (rc >= 0); +/* Returned events will be stored in items[].revents */ ---- SEE ALSO -------- linkzmq:zmq_socket[3] +linkzmq:zmq_send[3] +linkzmq:zmq_recv[3] +linkzmq:zmq[7] +Your operating system documentation for the _poll()_ system call. -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_queue.txt b/doc/zmq_queue.txt index 7f31ff9..a3f84f2 100644 --- a/doc/zmq_queue.txt +++ b/doc/zmq_queue.txt @@ -4,29 +4,30 @@ zmq_queue(1) NAME ---- -zmq_queue - forwards REQ/REP messages +zmq_queue - forwarding device for request-reply messaging SYNOPSIS -------- -* +To be written. DESCRIPTION ----------- -* +To be written. OPTIONS ------- -* +To be written. SEE ALSO -------- -* +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt index 0365d23..dbdf45f 100644 --- a/doc/zmq_recv.txt +++ b/doc/zmq_recv.txt @@ -4,51 +4,60 @@ zmq_recv(3) NAME ---- -zmq_recv - retrieves a message from the socket +zmq_recv - receive a message from a socket SYNOPSIS -------- -'int zmq_recv (void *s, zmq_msg_t *msg, int flags);' +*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');* DESCRIPTION ----------- -Receive a message from the socket 's', store it in -'msg' . Any content previously in 'msg' will be properly deallocated. 'flags' -argument can be combination of the flags described below. +The _zmq_recv()_ function shall dequeue a message from the underlying _message +queue_ associated with the socket referenced by the 'socket' argument and store +it in the message referenced by the 'msg' argument. Any content previously +stored in 'msg' shall be properly deallocated. If there are no 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*:: -The flag specifies that the operation should be performed in -non-blocking mode. I.e. if it cannot be processed immediately, -error should be returned with 'errno' set to EAGAIN. +Specifies that the operation should be performed in non-blocking mode. If there +are no messages available to be dequeued from the underlying _message queue_ +associated with 'socket', the _zmq_recv()_ function shall fail with 'errno' set +to EAGAIN. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_recv()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS ------ *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*:: -function isn't supported by particular socket type. +The _zmq_recv()_ operation is not supported by this socket type. *EFSM*:: -function cannot be called at the moment, because socket is not in the -appropriate state. This error may occur with sockets that switch between -several states (e.g. ZMQ_REQ). +The _zmq_recv()_ operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. EXAMPLE ------- +.Receiving a message from a socket ---- +/* Create an empty 0MQ message */ zmq_msg_t msg; int rc = zmq_msg_init (&msg); assert (rc == 0); -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); ---- @@ -56,11 +65,11 @@ assert (rc == 0); SEE ALSO -------- linkzmq:zmq_send[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] +linkzmq:zmq_socket[7] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt index f6a35c5..d2ae318 100644 --- a/doc/zmq_send.txt +++ b/doc/zmq_send.txt @@ -4,59 +4,69 @@ zmq_send(3) NAME ---- -zmq_send - sends a message +zmq_send - send a message on a socket SYNOPSIS -------- -'int zmq_send (void *s, zmq_msg_t *msg, int flags);' +*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');* DESCRIPTION ----------- -Send the message 'msg' to the socket 's'. 'flags' argument can be combination -the flags described below. +The _zmq_send()_ function shall queue the message referenced by the 'msg' +argument to be sent to the socket referenced by the 'socket' argument. The +'flags' argument is a combination of the flags defined below: *ZMQ_NOBLOCK*:: -The flag specifies that the operation should be performed in non-blocking mode. -I.e. if it cannot be processed immediately, error should be returned with -'errno' set to EAGAIN. +Specifies that the operation should be performed in non-blocking mode. If the +message cannot be queued on the underlying _message queue_ associated with +'socket', the _zmq_send()_ function shall fail with 'errno' set to EAGAIN. *ZMQ_NOFLUSH*:: -The flag specifies that 'zmq_send' should not flush the message downstream -immediately. Instead, it should batch ZMQ_NOFLUSH messages and send them -downstream only once 'zmq_flush' is invoked. This is an optimisation for cases -where several messages are sent in a single business transaction. However, the -effect is measurable only in extremely high-perf scenarios (million messages a -second or so). If that's not your case, use standard flushing send instead. +Specifies that the _zmq_send()_ function should not flush the underlying +_message queue_ associated with 'socket' to the network automatically. +Instead, it should batch all messages queued with the 'ZMQ_NOFLUSH' flag and +only flush the _message queue_ once either a message without the 'ZMQ_NOFLUSH' +flag is queued, or manually on invocation of the _zmq_flush()_ function. + +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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_send()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS ------ *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*:: -function isn't supported by particular socket type. +The _zmq_send()_ operation is not supported by this socket type. *EFSM*:: -function cannot be called at the moment, because socket is not in the -appropriate state. This error may occur with sockets that switch between -several states (e.g. ZMQ_REQ). +The _zmq_send()_ operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. EXAMPLE ------- +.Filling in a message and sending it to a socket ---- +/* Create a new message, allocating 6 bytes for message content */ zmq_msg_t msg; int rc = zmq_msg_init_size (&msg, 6); assert (rc == 0); +/* Fill in message content with 'AAAAAA' */ memset (zmq_msg_data (&msg), 'A', 6); -rc = zmq_send (s, &msg, 0); +/* Send the message to the socket */ +rc = zmq_send (socket, &msg, 0); assert (rc == 0); ---- @@ -65,13 +75,11 @@ SEE ALSO -------- linkzmq:zmq_flush[3] linkzmq:zmq_recv[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] +linkzmq:zmq_socket[7] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 629bffc..f230111 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -5,144 +5,255 @@ zmq_setsockopt(3) NAME ---- -zmq_setsockopt - sets a specified option on a 0MQ socket +zmq_setsockopt - set 0MQ socket options 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 ----------- -Sets an option on the socket. 'option' argument specifies the option from the -list below. 'optval' is a pointer to the value to set, 'optvallen' is the size -of the value in bytes. - -*ZMQ_HWM*:: -High watermark for the message pipes associated with the socket. The water -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. -+ -Type: int64_t Unit: messages Default: 0 - -*ZMQ_LWM*:: -Low watermark makes sense only if high watermark is defined (i.e. is non-zero). -When the emergency state is reached when messages overflow the pipe, the -emergency lasts at most till the size of the pipe decreases to low watermark. -Normal state is resumed at that point. -+ -Type: int64_t Unit: messages Default: 0 - -*ZMQ_SWAP*:: -Swap allows the pipe to exceed high watermark. However, the data are written -to the disk rather than held in the memory. Until high watermark is -exceeded there is no disk activity involved though. The value of the option -defines maximal size of the swap file. -+ -Type: int64_t Unit: bytes Default: 0 - -*ZMQ_AFFINITY*:: -Affinity defines which threads in the thread pool will be used to handle -newly created sockets. This way you can dedicate some of the threads (CPUs) -to a specific work. Value of 0 means no affinity. Work is distributed -fairly among the threads in the thread pool. For non-zero values, the lowest -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 -I/O activity exclusively using threads no. 1 and 2. -+ -Type: int64_t Unit: N/A (bitmap) Default: 0 - -*ZMQ_IDENTITY*:: -Identity of the socket. Identity is important when restarting applications. -If the socket has no identity, each run of the application is completely -separated from other runs. However, with identity application reconnects to -existing infrastructure left by the previous run. Thus it may receive -messages that were sent in the meantime, it shares pipe limits with the -previous run etc. Identity should be at least one byte and at most 255 bytes -long. Identities starting with binary zero are reserver for use by 0MQ -infrastructure. -+ -Type: BLOB Unit: N/A Default: NULL - -*ZMQ_SUBSCRIBE*:: -Applicable only to ZMQ_SUB socket type. It establishes new message filter. -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 -filters can be attached to a single 'sub' socket. In that case message passes -if it matches at least one of the filters. -+ -Type: BLOB Unit: N/A Default: N/A - -*ZMQ_UNSUBSCRIBE*:: -Applicable only to ZMQ_SUB socket type. Removes existing message filter. -The filter specified must match the string passed to ZMQ_SUBSCRIBE options -exactly. If there were several instances of the same filter created, -this options removes only one of them, leaving the rest in place -and functional. -+ -Type: BLOB Unit: N/A Default: N/A - -*ZMQ_RATE*:: -This option applies only to sending side of multicast transports (pgm & udp). -It specifies maximal outgoing data rate that an individual sender socket -can send. -+ -Type: uint64_t Unit: kilobits/second Default: 100 - -*ZMQ_RECOVERY_IVL*:: -This option applies only to multicast transports (pgm & udp). It specifies -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 -very large recovery buffers, meaning that you can easily overload your box -by setting say 1 minute recovery interval at 1Gb/s rate (requires -7GB in-memory buffer). -+ -Type: uint64_t Unit: seconds Default: 10 - -*ZMQ_MCAST_LOOP*:: -This option applies only to multicast transports (pgm & udp). Value of 1 -means that the mutlicast packets can be received on the box they were sent -from. Setting the value to 0 disables the loopback functionality which -can have negative impact on the performance. If possible, disable -the loopback in production environments. -+ -Type: uint64_t Unit: N/A (boolean value) Default: 1 - -*ZMQ_SNDBUF*:: -Sets the underlying kernel transmit buffer size to the specified size. See -'SO_SNDBUF' POSIX socket option. Value of zero means leaving the OS default -unchanged. -+ -Type: uint64_t Unit: bytes Default: 0 - -*ZMQ_RCVBUF*:: -Sets the underlying kernel receive buffer size to the specified size. See -'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default -unchanged. -+ -Type: uint64_t Unit: bytes Default: 0 +The _zmq_setsockopt()_ function shall set the option specified by the +'option_name' argument to the value pointed to by the 'option_value' argument +for the 0MQ socket pointed to by the 'socket' argument. The 'option_len' +argument is the size of the option value in bytes. + +The following options are defined: + + +ZMQ_HWM: Set high water mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +of outstanding messages in the queue; if this limit has been reached the socket +shall enter an "emergency" state and depending on the socket type, 0MQ shall +take appropriate action such as blocking or dropping new messages entering the +queue. + +The default 'ZMQ_HWM' value of zero means "no limit". + +Option value type:: int64_t +Option value unit:: messages +Default value:: 0 +Applicable socket types:: all + + +ZMQ_LWM: Set low water mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LWM' option shall set the low water mark for the _message queue_ +associated with the socket. This option only makes sense when used in +conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high +water mark remains in the "emergency" state until the number of outstanding +messages in it's associated message queue falls below the low water mark, at +which point normal message processing is resumed. + +Option value type:: int64_t +Option value unit:: messages +Default value:: 0 +Applicable socket types:: all + + +ZMQ_SWAP: Set disk offload size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the _message +queue_ associated with the socket. A socket which has 'ZMQ_SWAP' set to a +non-zero value may exceed it's high water mark; in this case outstanding +messages shall be offloaded to storage on disk rather than held in memory. + +The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes. + +Option value type:: int64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_AFFINITY: Set I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +'socket'. + +sockets. Affinity determines which threads from the 0MQ I/O thread pool +associated with the socket's _context_ shall handle newly created connections. +A value of zero specifies no affinity, meaning that work shall be distributed +fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the +lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. +For example, a value of 3 specifies that subsequent connections on 'socket' +shall be handled exclusively by I/O threads 1 and 2. + +See also linkzmq:zmq_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +Option value type:: int64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + + +ZMQ_IDENTITY: Set socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_IDENTITY' option shall set the identity of the socket. Socket identity +determines if existing 0MQ infastructure (_message queues_, _forwarding +devices_) shall be identified with a specific application and persist across +multiple runs of the application. + +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 +any existing 0MQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, _message +queue_ limits shall be shared with previous run(s) and so on. + +Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by 0MQ infrastructure. + +Option value type:: BLOB +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +ZMQ_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' +socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, +therefore you should call this option to establish an initial message filter. + +An empty 'option_value' of length zero shall subscribe to all incoming +messages. A non-empty 'option_value' shall subscribe to all messages beginning +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 ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it +shall return -1 and set 'errno' to one of the values defined below. ERRORS ------ *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 ------- +.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); +/* 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] linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index b6cdc35..c53779c 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -4,110 +4,117 @@ zmq_socket(3) NAME ---- -zmq_socket - creates 0MQ socket +zmq_socket - create 0MQ socket SYNOPSIS -------- -'void *zmq_socket (void *context, int type);' +*void *zmq_socket (void '*context', int 'type');* DESCRIPTION ----------- -Open a socket within the specified 'context'. To create a context, use -'zmq_init' function. 'type' argument can be one of the values defined below. -Note that each socket is owned by exactly one thread (the one that it was -created from) and should not be used from any other thread. - -*ZMQ_P2P*:: -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. -+ -Compatible peer sockets: ZMQ_P2P. - -*ZMQ_PUB*:: -Socket to distribute data. Recv function is not implemented for this socket -type. Messages are distributed in fanout fashion to all the peers. -+ -Compatible peer sockets: ZMQ_SUB. - -*ZMQ_SUB*:: -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. -+ -Compatible peer sockets: ZMQ_PUB. - -*ZMQ_REQ*:: -Socket to send requests and receive replies. Requests are load-balanced among -all the peers. This socket type allows only an alternated sequence of send's -and recv's. -+ -Compatible peer sockets: ZMQ_REP, ZMQ_XREP. - -*ZMQ_REP*:: -Socket to receive requests and send replies. This socket type allows only an -alternated sequence of recv's and send's. Each send is routed to the peer that -issued the last received request. -+ -Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ. - -*ZMQ_XREQ*:: -Special socket type to be used in request/reply middleboxes such as -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 -reply back to the original requester. -+ -Compatible peer sockets: ZMQ_REP, ZMQ_XREP. - -*ZMQ_XREP*:: -Special socket type to be used in request/reply middleboxes such as -linkzmq:zmq_queue[7]. Requests received using this socket are already properly -tagged with prefix identifying the original requester. When sending a reply via -XREP socket the message should be tagged with a prefix from a corresponding -request. -+ -Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ. - -*ZMQ_UPSTREAM*:: -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 -type. -+ -Compatible peer sockets: ZMQ_DOWNSTREAM. - -*ZMQ_DOWNSTREAM*:: -Socket to send messages down stream. Messages are load-balanced among all the -connected peers. Recv function is not implemented for this socket type. -+ -Compatible peer sockets: ZMQ_UPSTREAM. +The 'zmq_socket()' function shall create a 0MQ socket within the specified +'context' and return an opaque handle to the newly created socket. The 'type' +argument specifies the _messaging pattern_, which determines the semantics of +communication over the socket. + +The following _messaging patterns_ are defined: + + +Peer to peer pattern +~~~~~~~~~~~~~~~~~~~~ +The simplest messaging pattern, used for communicating between two peers. + +Socket type:: 'ZMQ_P2P' +Compatible peer sockets:: 'ZMQ_P2P' + +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_P2P' socket. + + +Publish-subscribe pattern +~~~~~~~~~~~~~~~~~~~~~~~~~ +The publish-subscribe pattern is used for one-to-many distribution of data from +a single _publisher_ to multiple _subscribers_ in a fanout fashion. + +Socket type:: 'ZMQ_PUB' +Compatible peer sockets:: 'ZMQ_SUB' + +A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. +Messages sent are distributed in a fanout fashion to all connected peers. +The _zmq_recv()_ function is not implemented for this socket type. + +Socket type:: 'ZMQ_SUB' +Compatible peer sockets:: 'ZMQ_PUB' + +A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data +distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to +any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify +which messages to subscribe to. The _zmq_send()_ function is not implemented +for this socket type. + + +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a _client_ to a +_service_, and receiving subsequent replies to each request sent. + +Socket type:: 'ZMQ_REQ' +Compatible peer sockets:: 'ZMQ_REP' + +A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and +receive replies from a _service_. This socket type allows only an alternating +sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each +request sent is load-balanced among all connected _services_. + +Socket type:: 'ZMQ_REP' +Compatible peer sockets:: 'ZMQ_REQ' + +A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and +send replies to a _client_. This socket type allows only an alternating +sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each +reply is routed to the _client_ that issued the last received request. + + +Parallelized pipeline pattern +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The parallelized pipeline pattern is used for distributing work between +_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 ------------ -Function returns socket handle is successful. Otherwise it returns NULL and -sets errno to one of the values below. +The _zmq_socket()_ function shall return an opaque handle to the newly created +socket if successful. Otherwise, it shall return NULL and set 'errno' to one of +the values defined below. ERRORS ------ *EINVAL*:: - invalid socket type. +The requested socket 'type' is invalid. *EMTHREAD*:: - the number of application threads allowed to own 0MQ sockets was exceeded. - See 'app_threads' parameter to '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); ----- +The number of application threads using sockets within this 'context' has been +exceeded. See the 'app_threads' parameter of the _zmq_init()_ function. SEE ALSO @@ -121,6 +128,7 @@ linkzmq:zmq_flush[3] linkzmq:zmq_recv[3] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_streamer.txt b/doc/zmq_streamer.txt index d0df514..c8d517b 100644 --- a/doc/zmq_streamer.txt +++ b/doc/zmq_streamer.txt @@ -4,29 +4,30 @@ zmq_streamer(1) NAME ---- -zmq_streamer - forwards the stream of UPSTREAM/DOWNSTREAM messages +zmq_streamer - streamer device for parallelized pipeline messaging SYNOPSIS -------- -* +To be written. DESCRIPTION ----------- -* +To be written. OPTIONS ------- -* +To be written. SEE ALSO -------- -* +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt index 2bdf762..61f30e3 100644 --- a/doc/zmq_strerror.txt +++ b/doc/zmq_strerror.txt @@ -4,24 +4,27 @@ zmq_strerror(3) NAME ---- -zmq_strerror - returns string describing the error number +zmq_strerror - get 0MQ error message string SYNOPSIS -------- -'const char *zmq_strerror (int errnum);' +*const char *zmq_strerror (int 'errnum');* DESCRIPTION ----------- -As 0MQ defines few additional (non-POSIX) error codes, standard -'strerror' isn't capable of translating those errors into human readable -strings. Instead, 'zmq_strerror' should be used. +The _zmq_strerror()_ function shall return a pointer to an error message string +corresponding to the error number specified by the 'errnum' argument. As 0MQ +defines additional error numbers over and above those defined by the operating +system, applications should use _zmq_strerror()_ in preference to the standard +_strerror()_ function. RETURN VALUE ------------ -Returns string describing the error number. +The _zmq_strerror()_ function shall return a pointer to an error message +string. ERRORS @@ -31,10 +34,11 @@ No errors are defined. EXAMPLE ------- +.Displaying an error message when a 0MQ context cannot be initialised ---- void *ctx = zmq_init (1, 1, 0); if (!ctx) { - printf ("error occured during zmq_init: %s\\n", zmq_strerror (errno)); + printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno)); abort (); } ---- @@ -45,6 +49,7 @@ SEE ALSO linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index 98f1219..c6eba21 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -4,55 +4,72 @@ zmq_tcp(7) NAME ---- -zmq_tcp - 0MQ unicast TCP transport over the network +zmq_tcp - 0MQ unicast transport using TCP SYNOPSIS -------- -TCP is an ubiquitous unicast transport. When connecting distributed -applications, you will mostly use TCP transport. +TCP is an ubiquitous, reliable, unicast transport. When connecting distributed +applications over a network with 0MQ, using the TCP transport will likely be +your first choice. -CONNECTION STRING ------------------ -Connection string for TCP transport is "tcp://" followed by an IP address, -colon and port number. IP address can be either its numeric representation, -a NIC name or a hostname (resolved by DNS): +ADDRESSING +---------- +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 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 -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. +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When assigning a local address to a socket using _zmq_bind()_ with the 'tcp' +transport, the 'endpoint' shall be interpreted as an 'interface' followed by a +colon and the TCP port number to use. +An 'interface' may be specified by either of the following: -WIRE FORMAT ------------ -A message consists of a message length followed by message data. -Size of message data MUST correspond to the message length. +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric representation. +* The wildcard `*`, meaning that the interface address is unspecified. -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 -%xFF followed by a 64-bit unsigned integer length in network byte order. +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp' +transport, the 'endpoint' shall be interpreted as a 'peer address' followed by +a colon and the TCP port number to use. -The protocol can be defined by this BNF grammar: +A 'peer address' may be specified by either of the following: ----- - frame = length data - length = OCTET | escape 8*OCTET - escape = %xFF - data = *OCTET ----- +* The DNS name of the peer. +* The IPv4 address of the peer, in it's numeric representation. -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 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): +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 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 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: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 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 -------- -linkzmq:zmq_udp[7] +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] linkzmq:zmq_pgm[7] linkzmq:zmq_ipc[7] linkzmq:zmq_inproc[7] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> - +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt index 451c1ac..eea9f48 100644 --- a/doc/zmq_term.txt +++ b/doc/zmq_term.txt @@ -4,25 +4,27 @@ zmq_term(3) NAME ---- -zmq_term - terminates 0MQ context +zmq_term - terminate 0MQ context SYNOPSIS -------- -'int zmq_term (void *context);' +*int zmq_term (void '*context');* DESCRIPTION ----------- -Destroys 0MQ context. However, if there are still any sockets open within -the context, 'zmq_term' succeeds but shutdown of the context is delayed till -the last socket is closed. +The _zmq_term()_ function terminates the 0MQ context 'context'. + +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 ------------ -Function returns zero is successful. Otherwise it returns -1 and sets errno to -one of the values below. +The _zmq_term()_ function shall return zero if successful. Otherwise it shall +return -1 and set 'errno' to one of the values defined below. ERRORS @@ -30,20 +32,13 @@ ERRORS No errors are defined. -EXAMPLE -------- ----- -int rc = zmq_term (context); -assert (rc == 0); ----- - - SEE ALSO -------- +linkzmq:zmq[7] linkzmq:zmq_init[3] -linkzmq:zmq_close[3] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. diff --git a/doc/zmq_udp.txt b/doc/zmq_udp.txt deleted file mode 100644 index ecc6bdf..0000000 --- a/doc/zmq_udp.txt +++ /dev/null @@ -1,56 +0,0 @@ -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> - diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt index 8c038ae..0ad3a55 100644 --- a/doc/zmq_version.txt +++ b/doc/zmq_version.txt @@ -4,19 +4,24 @@ zmq_version(3) NAME ---- -zmq_version - reports 0MQ version +zmq_version - report 0MQ library version SYNOPSIS -------- -'void zmq_version (int *major, int *minor, int *patch);' +*void zmq_version (int '*major', int '*minor', int '*patch');* DESCRIPTION ----------- -Returns current version of 0MQ. The functionality is useful for applications -linking with 0MQ dynamically to make sure the right version of 0MQ is installed -on the system. +The _zmq_version()_ function shall fill in the integer variables pointed to by +the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel +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 ------------ @@ -30,6 +35,7 @@ No errors are defined. EXAMPLE ------- +.Printing out the version of the 0MQ library ---- int major, minor, patch; zmq_version (&major, &minor, &patch); @@ -41,6 +47,7 @@ SEE ALSO -------- linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. |