diff options
Diffstat (limited to 'doc/zmq.txt')
-rw-r--r-- | doc/zmq.txt | 227 |
1 files changed, 137 insertions, 90 deletions
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. |