2010-01-05 08:29:35 +01:00
|
|
|
.TH zmq 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
|
2009-11-22 08:47:06 +01:00
|
|
|
.SH NAME
|
|
|
|
|
0MQ \- a lightweight messaging kernel
|
|
|
|
|
.SH SYNOPSIS
|
2009-12-04 10:06:46 +01:00
|
|
|
|
|
|
|
|
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
|
|
|
|
|
datacenters.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
.SH 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:
|
|
|
|
|
.BR zmq_init(3)
|
|
|
|
|
|
|
|
|
|
Uninitialise 0MQ context:
|
|
|
|
|
.BR zmq_term(3)
|
|
|
|
|
|
|
|
|
|
.SH 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:
|
|
|
|
|
.BR zmq_msg_init(3)
|
|
|
|
|
.BR zmq_msg_size(3)
|
|
|
|
|
.BR zmq_msg_data(3)
|
|
|
|
|
|
|
|
|
|
Uninitialise a message:
|
|
|
|
|
.BR zmq_msg_close(3)
|
|
|
|
|
|
|
|
|
|
Access message content:
|
|
|
|
|
.BR zmq_msg_data(3)
|
|
|
|
|
.BR zmq_msg_size(3)
|
|
|
|
|
|
|
|
|
|
Message manipulation:
|
|
|
|
|
.BR zmq_msg_copy(3)
|
|
|
|
|
.BR zmq_msg_move(3)
|
|
|
|
|
|
|
|
|
|
.SH SOCKETS
|
|
|
|
|
0MQ sockets are very similar to POSIX sockets. See following manual pages to
|
|
|
|
|
understand them in depth.
|
|
|
|
|
|
|
|
|
|
Creating a socket:
|
|
|
|
|
.BR zmq_socket(3)
|
|
|
|
|
|
|
|
|
|
Closing a socket:
|
|
|
|
|
.BR zmq_close(3)
|
|
|
|
|
|
|
|
|
|
Setting socket options:
|
|
|
|
|
.BR zmq_setsockopt(3)
|
|
|
|
|
|
|
|
|
|
Establishing a message flow:
|
|
|
|
|
.BR zmq_bind(3)
|
|
|
|
|
.BR zmq_connect(3)
|
|
|
|
|
|
|
|
|
|
Sending & receiving messages:
|
|
|
|
|
.BR zmq_send(3)
|
|
|
|
|
.BR zmq_flush(3)
|
|
|
|
|
.BR zmq_recv(3)
|
|
|
|
|
|
|
|
|
|
.SH MULTIPLEXING
|
|
|
|
|
0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
|
|
|
|
|
in an asynchronous manner.
|
|
|
|
|
|
|
|
|
|
Poll for I/O events:
|
|
|
|
|
.BR zmq_poll(3)
|
|
|
|
|
|
|
|
|
|
.SH ERROR HANDLING
|
|
|
|
|
0MQ defines couple of non-POSIX error codes. Use following fuctions to handle
|
|
|
|
|
them neatly.
|
|
|
|
|
|
|
|
|
|
Convert error code into human readable string:
|
|
|
|
|
.BR zmq_strerror(3)
|
|
|
|
|
|
|
|
|
|
.SH 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:
|
|
|
|
|
.BR zmq_tcp(7)
|
|
|
|
|
|
|
|
|
|
UDP reliable multicast transport:
|
|
|
|
|
.BR zmq_udp(7)
|
|
|
|
|
|
|
|
|
|
PGM reliable multicast transport:
|
|
|
|
|
.BR zmq_pgm(7)
|
|
|
|
|
|
|
|
|
|
In-process (inter-thread) transport:
|
|
|
|
|
.BR zmq_inproc(7)
|
|
|
|
|
|
|
|
|
|
.SH 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:
|
|
|
|
|
.BR zmq_forwarder(1)
|
|
|
|
|
|
|
|
|
|
Streamer device for UPSTREAM/DOWNSTREAM messaging:
|
|
|
|
|
.BR zmq_streamer(1)
|
|
|
|
|
.SH 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++:
|
|
|
|
|
.BR zmq_cpp(7)
|
|
|
|
|
|
|
|
|
|
Common Lisp:
|
|
|
|
|
.BR zmq_cl(7)
|
|
|
|
|
|
|
|
|
|
Python:
|
|
|
|
|
.BR zmq_python(7)
|
|
|
|
|
|
|
|
|
|
Ruby:
|
|
|
|
|
.BR zmq_ruby(7)
|
|
|
|
|
|
2009-11-22 08:47:06 +01:00
|
|
|
.SH AUTHOR
|
2009-12-04 10:06:46 +01:00
|
|
|
Martin Sustrik <sustrik at 250bpm dot com>
|
2009-11-22 08:47:06 +01:00
|
|
|
|
