1ZMQ(7) 0MQ Manual ZMQ(7)
2
6 zmq - 0MQ lightweight messaging kernel
7
9 #include <zmq.h>
10 cc [flags] files -lzmq [libraries]
12
14 The 0MQ lightweight messaging kernel is a library which extends the
15 standard socket interfaces with features traditionally provided by
16 specialised messaging middleware products. 0MQ sockets provide an
17 abstraction of asynchronous message queues, multiple messaging
18 patterns, message filtering (subscriptions), seamless access to
19 multiple transport protocols and more.
20 This documentation presents an overview of 0MQ concepts, describes how
22 0MQ abstracts standard sockets and provides a reference manual for the
23 functions provided by the 0MQ library.
24 Context
26 Before using any 0MQ library functions the caller must initialise a 0MQ
27 context using zmq_init(). The following functions are provided to
28 handle initialisation and termination of a context:
29 Initialise 0MQ context
31 zmq_init(3)
33 Terminate 0MQ context
35 zmq_term(3)
37 Thread safety
39 A 0MQ context is thread safe and may be shared among as many
40 application threads as necessary, without any additional locking
41 required on the part of the caller.
42 Individual 0MQ sockets are not thread safe except in the case where
44 full memory barriers are issued when migrating a socket from one
45 thread to another. In practice this means applications can create a
46 socket in one thread with zmq_socket() and then pass it to a newly
47 created thread as part of thread initialization, for example via a
48 structure passed as an argument to pthread_create().
49 Multiple contexts
51 Multiple contexts may coexist within a single application. Thus, an
52 application can use 0MQ directly and at the same time make use of
53 any number of additional libraries or components which themselves
54 make use of 0MQ as long as the above guidelines regarding thread
55 safety are adhered to.
56 Messages
58 A 0MQ message is a discrete unit of data passed between applications or
59 components of the same application. 0MQ messages have no internal
60 structure and from the point of view of 0MQ itself they are considered
61 to be opaque binary data.
62 The following functions are provided to work with messages:
64 Initialise a message
66 zmq_msg_init(3) zmq_msg_init_size(3) zmq_msg_init_data(3)
68 Release a message
70 zmq_msg_close(3)
72 Access message content
74 zmq_msg_data(3) zmq_msg_size(3)
76 Message manipulation
78 zmq_msg_copy(3) zmq_msg_move(3)
80 Sockets
82 0MQ sockets present an abstraction of a asynchronous message queue,
83 with the exact queueing semantics depending on the socket type in use.
84 See zmq_socket(3) for the socket types provided.
85 The following functions are provided to work with sockets:
87 Creating a socket
89 zmq_socket(3)
91 Closing a socket
93 zmq_close(3)
95 Manipulating socket options
97 zmq_getsockopt(3) zmq_setsockopt(3)
99 Establishing a message flow
101 zmq_bind(3) zmq_connect(3)
103 Sending and receiving messages
105 zmq_send(3) zmq_recv(3)
107 Input/output multiplexing. 0MQ provides a mechanism for applications to
109 multiplex input/output events over a set containing both 0MQ sockets
110 and standard sockets. This mechanism mirrors the standard poll() system
111 call, and is described in detail in zmq_poll(3).
112 Transports
114 A 0MQ socket can use multiple different underlying transport
115 mechanisms. Each transport mechanism is suited to a particular purpose
116 and has its own advantages and drawbacks.
117 The following transport mechanisms are provided:
119 Unicast transport using TCP
121 zmq_tcp(7)
123 Reliable multicast transport using PGM
125 zmq_pgm(7)
127 Local inter-process communication transport
129 zmq_ipc(7)
131 Local in-process (inter-thread) communication transport
133 zmq_inproc(7)
135 Devices
137 0MQ provides devices, which are building blocks that act as
138 intermediate nodes in complex messaging topologies. Devices can act as
139 brokers that other nodes connect to, proxies that connect through to
140 other nodes, or any mix of these two models.
141 You can start a device in an application thread, see zmq_device(3).
143
145 The 0MQ library functions handle errors using the standard conventions
146 found on POSIX systems. Generally, this means that upon failure a 0MQ
147 library function shall return either a NULL value (if returning a
148 pointer) or a negative value (if returning an integer), and the actual
149 error code shall be stored in the errno variable.
150 On non-POSIX systems some users may experience issues with retrieving
152 the correct value of the errno variable. The zmq_errno() function is
153 provided to assist in these cases; for details refer to zmq_errno(3).
154 The zmq_strerror() function is provided to translate 0MQ-specific error
156 codes into error message strings; for details refer to zmq_strerror(3).
157
159 The following miscellaneous functions are provided:
160 Report 0MQ library version
162 zmq_version(3)
164
166 The 0MQ library provides interfaces suitable for calling from programs
167 in any language; this documentation documents those interfaces as they
168 would be used by C programmers. The intent is that programmers using
169 0MQ from other languages shall refer to this documentation alongside
170 any documentation provided by the vendor of their language binding.
171 C++ language binding
173 The 0MQ distribution includes a C++ language binding, which is
174 documented separately in zmq_cpp(7).
175 Other language bindings
177 Other language bindings (Python, Ruby, Java and more) are provided by
178 members of the 0MQ community and pointers can be found on the 0MQ
179 website.
180
182 This 0MQ manual page was written by Martin Sustrik
183 <sustrik@250bpm.com[1]> and Martin Lucina <mato@kotelna.sk[2]>.
184
186 Main web site: http://www.zeromq.org/
187 Report bugs to the 0MQ development mailing list:
189 <zeromq-dev@lists.zeromq.org[3]>
190
192 Free use of this software is granted under the terms of the GNU Lesser
193 General Public License (LGPL). For details see the files COPYING and
194 COPYING.LESSER included with the 0MQ distribution.
195
197 1. sustrik@250bpm.com
198 mailto:sustrik@250bpm.com
199 2. mato@kotelna.sk
201 mailto:mato@kotelna.sk
202 3. zeromq-dev@lists.zeromq.org
204 mailto:zeromq-dev@lists.zeromq.org
2050MQ 2.1.4 03/30/2011 ZMQ(7)