diff options
Diffstat (limited to 'doc/zmq.txt')
| -rw-r--r-- | doc/zmq.txt | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/doc/zmq.txt b/doc/zmq.txt new file mode 100644 index 0000000..0c911c3 --- /dev/null +++ b/doc/zmq.txt @@ -0,0 +1,175 @@ +zmq(7) +====== + + +NAME +---- +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. + +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. + +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. + +0MQ is accessible from a large set of programming languages. + +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. + +Initialise 0MQ context:: + linkzmq:zmq_init[3] + +Uninitialise 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. + +Initialise a message:: + linkzmq:zmq_msg_init[3] + linkzmq:zmq_msg_size[3] + linkzmq:zmq_msg_data[3] + +Uninitialise a message:: + linkzmq:zmq_msg_close[3] + +Access message content:: + linkzmq:zmq_msg_data[3] + linkzmq:zmq_msg_size[3] + +Message manipulation:: + linkzmq:zmq_msg_copy[3] + linkzmq:zmq_msg_move[3] + + +SOCKETS +------- +0MQ sockets are very similar to POSIX sockets. See following manual pages to +understand them in depth. + +Creating a socket:: + linkzmq:zmq_socket[3] + +Closing a socket:: + linkzmq:zmq_close[3] + +Setting socket options:: + linkzmq:zmq_setsockopt[3] + +Establishing a message flow:: + linkzmq:zmq_bind[3] + linkzmq:zmq_connect[3] + +Sending & 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] + + +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 +---------- +0MQ allows for using different underlying transport mechanisms (even multiple +at once). Each transport mechanism has its own advantages and drawbacks. For +detailed description of individual mechanisms check following manual pages: + +TCP/IP transport:: + linkzmq:zmq_tcp[7] + +UDP reliable multicast transport:: + linkzmq:zmq_udp[7] + +PGM reliable multicast transport:: + linkzmq:zmq_pgm[7] + +Inter-process transport:: + linkzmq:zmq_ipc[7] + +In-process (inter-thread) 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: + +Forwarder device for PUB/SUB messaging:: + linkzmq:zmq_forwarder[1] + +Streamer device for UPSTREAM/DOWNSTREAM messaging:: + linkzmq:zmq_streamer[1] + +Forwarder device for REQ/REP messaging:: + linkzmq:zmq_queue[1] + + +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] + +Java:: + linkzmq:zmq_java[7] + +Python:: + linkzmq:zmq_python[7] + + +AUTHOR +------ +Martin Sustrik <sustrik at 250bpm dot com> |