From 1aee86408d575d6572b071d7564da7f006d1757e Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Tue, 9 Mar 2010 18:47:31 +0100 Subject: Documentation rewrite --- doc/Makefile.am | 4 +- doc/asciidoc.conf | 8 ++ doc/zmq.txt | 227 ++++++++++++++++++------------ doc/zmq_bind.txt | 60 +++++--- doc/zmq_close.txt | 37 +++-- doc/zmq_connect.txt | 60 +++++--- doc/zmq_epgm.txt | 1 + doc/zmq_flush.txt | 48 +++---- doc/zmq_forwarder.txt | 17 +-- doc/zmq_init.txt | 52 ++++--- doc/zmq_inproc.txt | 85 ++++++++--- doc/zmq_ipc.txt | 72 +++++++--- doc/zmq_java.txt | 27 ---- doc/zmq_msg_close.txt | 43 +++--- doc/zmq_msg_copy.txt | 46 +++--- doc/zmq_msg_data.txt | 32 ++--- doc/zmq_msg_init.txt | 29 ++-- doc/zmq_msg_init_data.txt | 51 ++++--- doc/zmq_msg_init_size.txt | 51 +++---- doc/zmq_msg_move.txt | 38 +++-- doc/zmq_msg_size.txt | 35 ++--- doc/zmq_pgm.txt | 174 +++++++++++++---------- doc/zmq_poll.txt | 122 ++++++++++------ doc/zmq_queue.txt | 17 +-- doc/zmq_recv.txt | 53 ++++--- doc/zmq_send.txt | 66 +++++---- doc/zmq_setsockopt.txt | 348 ++++++++++++++++++++++++++++++---------------- doc/zmq_socket.txt | 184 ++++++++++++------------ doc/zmq_streamer.txt | 17 +-- doc/zmq_strerror.txt | 25 ++-- doc/zmq_tcp.txt | 129 +++++++++++------ doc/zmq_term.txt | 33 ++--- doc/zmq_udp.txt | 56 -------- doc/zmq_version.txt | 23 +-- 34 files changed, 1297 insertions(+), 973 deletions(-) create mode 120000 doc/zmq_epgm.txt delete mode 100644 doc/zmq_java.txt delete mode 100644 doc/zmq_udp.txt (limited to 'doc') 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)[\\]?(?Plinkzmq):(?P\S*?)\[(?P.*?)\]= @@ -32,3 +35,8 @@ template::[header-declarations] 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 * -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 + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . + + +RESOURCES +--------- +Main web site: + +Report bugs to the 0MQ development mailing list: + + +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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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 +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . 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