1ZMQ_SOCKET(3) 0MQ Manual ZMQ_SOCKET(3)
2
6 zmq_socket - create 0MQ socket
7
9 void *zmq_socket (void *context, int type);
10
12 The zmq_socket() function shall create a 0MQ socket within the
13 specified context and return an opaque handle to the newly created
14 socket. The type argument specifies the socket type, which determines
15 the semantics of communication over the socket.
16 The newly created socket is initially unbound, and not associated with
18 any endpoints. In order to establish a message flow a socket must first
19 be connected to at least one endpoint with zmq_connect(3), or at least
20 one endpoint must be created for accepting incoming connections with
21 zmq_bind(3).
22 Key differences to conventional sockets. Generally speaking,
24 conventional sockets present a synchronous interface to either
25 connection-oriented reliable byte streams (SOCK_STREAM), or
26 connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ
27 sockets present an abstraction of an asynchronous message queue, with
28 the exact queueing semantics depending on the socket type in use. Where
29 conventional sockets transfer streams of bytes or discrete datagrams,
30 0MQ sockets transfer discrete messages.
31 0MQ sockets being asynchronous means that the timings of the physical
33 connection setup and tear down, reconnect and effective delivery are
34 transparent to the user and organized by 0MQ itself. Further, messages
35 may be queued in the event that a peer is unavailable to receive them.
36 Conventional sockets allow only strict one-to-one (two peers),
38 many-to-one (many clients, one server), or in some cases one-to-many
39 (multicast) relationships. With the exception of ZMQ_PAIR, 0MQ sockets
40 may be connected to multiple endpoints using zmq_connect(), while
41 simultaneously accepting incoming connections from multiple endpoints
42 bound to the socket using zmq_bind(), thus allowing many-to-many
43 relationships.
44 Thread safety. 0MQ sockets are not thread safe. Applications MUST NOT
46 use a socket from multiple threads except after migrating a socket from
47 one thread to another with a "full fence" memory barrier.
48 Socket types. The following sections present the socket types defined
50 by 0MQ, grouped by the general messaging pattern which is built from
51 related socket types.
52 Request-reply pattern
54 The request-reply pattern is used for sending requests from a client to
55 one or more instances of a service, and receiving subsequent replies to
56 each request sent.
57 ZMQ_REQ
59 A socket of type ZMQ_REQ is used by a client to send requests to
60 and receive replies from a service. This socket type allows only an
61 alternating sequence of zmq_send(request) and subsequent
62 zmq_recv(reply) calls. Each request sent is load-balanced among all
63 services, and each reply received is matched with the last issued
64 request.
65 When a ZMQ_REQ socket enters an exceptional state due to having
67 reached the high water mark for all services, or if there are no
68 services at all, then any zmq_send(3) operations on the socket
69 shall block until the exceptional state ends or at least one
70 service becomes available for sending; messages are not discarded.
71 Table 1. Summary of ZMQ_REQ characteristics
73 Compatible peer sockets ZMQ_REP
74 Direction Bidirectional
76 Send/receive pattern Send, Receive, Send,
78 Receive, ...
79 Outgoing routing strategy Load-balanced
81 Incoming routing strategy Last peer
83 ZMQ_HWM option action Block
85 ZMQ_REP
88 A socket of type ZMQ_REP is used by a service to receive requests
89 from and send replies to a client. This socket type allows only an
90 alternating sequence of zmq_recv(request) and subsequent
91 zmq_send(reply) calls. Each request received is fair-queued from
92 among all clients, and each reply sent is routed to the client that
93 issued the last request. If the original requester doesn’t exist
94 any more the reply is silently discarded.
95 When a ZMQ_REP socket enters an exceptional state due to having
97 reached the high water mark for a client, then any replies sent to
98 the client in question shall be dropped until the exceptional state
99 ends.
100 Table 2. Summary of ZMQ_REP characteristics
102 Compatible peer sockets ZMQ_REQ
103 Direction Bidirectional
105 Send/receive pattern Receive, Send, Receive,
107 Send, ...
108 Incoming routing strategy Fair-queued
110 Outgoing routing strategy Last peer
112 ZMQ_HWM option action Drop
114 ZMQ_DEALER
117 A socket of type ZMQ_DEALER is an advanced pattern used for
118 extending request/reply sockets. Each message sent is load-balanced
119 among all connected peers, and each message received is fair-queued
120 from all connected peers.
121 Previously this socket was called ZMQ_XREQ and that name remains
123 available for backwards compatibility.
124 When a ZMQ_DEALER socket enters an exceptional state due to having
126 reached the high water mark for all peers, or if there are no peers
127 at all, then any zmq_send(3) operations on the socket shall block
128 until the exceptional state ends or at least one peer becomes
129 available for sending; messages are not discarded.
130 When a ZMQ_DEALER socket is connected to a ZMQ_REP socket each
132 message sent must consist of an empty message part, the delimiter,
133 followed by one or more body parts.
134 Table 3. Summary of ZMQ_DEALER characteristics
136 Compatible peer sockets ZMQ_ROUTER, ZMQ_REP
137 Direction Bidirectional
139 Send/receive pattern Unrestricted
141 Outgoing routing strategy Load-balanced
143 Incoming routing strategy Fair-queued
145 ZMQ_HWM option action Block
147 ZMQ_ROUTER
150 A socket of type ZMQ_ROUTER is an advanced pattern used for
151 extending request/reply sockets. When receiving messages a
152 ZMQ_ROUTER socket shall prepend a message part containing the
153 identity of the originating peer to the message before passing it
154 to the application. Messages received are fair-queued from among
155 all connected peers. When sending messages a ZMQ_ROUTER socket
156 shall remove the first part of the message and use it to determine
157 the identity of the peer the message shall be routed to. If the
158 peer does not exist anymore the message shall be silently
159 discarded.
160 Previously this socket was called ZMQ_XREP and that name remains
162 available for backwards compatibility.
163 When a ZMQ_ROUTER socket enters an exceptional state due to having
165 reached the high water mark for all peers, or if there are no peers
166 at all, then any messages sent to the socket shall be dropped until
167 the exceptional state ends. Likewise, any messages routed to a
168 non-existent peer or a peer for which the individual high water
169 mark has been reached shall also be dropped.
170 When a ZMQ_REQ socket is connected to a ZMQ_ROUTER socket, in
172 addition to the identity of the originating peer each message
173 received shall contain an empty delimiter message part. Hence, the
174 entire structure of each received message as seen by the
175 application becomes: one or more identity parts, delimiter part,
176 one or more body parts. When sending replies to a ZMQ_REQ socket
177 the application must include the delimiter part.
178 Table 4. Summary of ZMQ_ROUTER characteristics
180 Compatible peer sockets ZMQ_DEALER, ZMQ_REQ
181 Direction Bidirectional
183 Send/receive pattern Unrestricted
185 Outgoing routing strategy See text
187 Incoming routing strategy Fair-queued
189 ZMQ_HWM option action Drop
191 Publish-subscribe pattern
194 The publish-subscribe pattern is used for one-to-many distribution of
195 data from a single publisher to multiple subscribers in a fan out
196 fashion.
197 ZMQ_PUB
199 A socket of type ZMQ_PUB is used by a publisher to distribute data.
200 Messages sent are distributed in a fan out fashion to all connected
201 peers. The zmq_recv(3) function is not implemented for this socket
202 type.
203 When a ZMQ_PUB socket enters an exceptional state due to having
205 reached the high water mark for a subscriber, then any messages
206 that would be sent to the subscriber in question shall instead be
207 dropped until the exceptional state ends. The zmq_send() function
208 shall never block for this socket type.
209 Table 5. Summary of ZMQ_PUB characteristics
211 Compatible peer sockets ZMQ_SUB
212 Direction Unidirectional
214 Send/receive pattern Send only
216 Incoming routing strategy N/A
218 Outgoing routing strategy Fan out
220 ZMQ_HWM option action Drop
222 ZMQ_SUB
225 A socket of type ZMQ_SUB is used by a subscriber to subscribe to
226 data distributed by a publisher. Initially a ZMQ_SUB socket is not
227 subscribed to any messages, use the ZMQ_SUBSCRIBE option of
228 zmq_setsockopt(3) to specify which messages to subscribe to. The
229 zmq_send() function is not implemented for this socket type.
230 Table 6. Summary of ZMQ_SUB characteristics
232 Compatible peer sockets ZMQ_PUB
233 Direction Unidirectional
235 Send/receive pattern Receive only
237 Incoming routing strategy Fair-queued
239 Outgoing routing strategy N/A
241 ZMQ_HWM option action Drop
243 Pipeline pattern
246 The pipeline pattern is used for distributing data to nodes arranged in
247 a pipeline. Data always flows down the pipeline, and each stage of the
248 pipeline is connected to at least one node. When a pipeline stage is
249 connected to multiple nodes data is load-balanced among all connected
250 nodes.
251 ZMQ_PUSH
253 A socket of type ZMQ_PUSH is used by a pipeline node to send
254 messages to downstream pipeline nodes. Messages are load-balanced
255 to all connected downstream nodes. The zmq_recv() function is not
256 implemented for this socket type.
257 When a ZMQ_PUSH socket enters an exceptional state due to having
259 reached the high water mark for all downstream nodes, or if there
260 are no downstream nodes at all, then any zmq_send(3) operations on
261 the socket shall block until the exceptional state ends or at least
262 one downstream node becomes available for sending; messages are not
263 discarded.
264 Deprecated alias: ZMQ_DOWNSTREAM.
266 Table 7. Summary of ZMQ_PUSH characteristics
268 Compatible peer sockets ZMQ_PULL
269 Direction Unidirectional
271 Send/receive pattern Send only
273 Incoming routing strategy N/A
275 Outgoing routing strategy Load-balanced
277 ZMQ_HWM option action Block
279 ZMQ_PULL
282 A socket of type ZMQ_PULL is used by a pipeline node to receive
283 messages from upstream pipeline nodes. Messages are fair-queued
284 from among all connected upstream nodes. The zmq_send() function is
285 not implemented for this socket type.
286 Deprecated alias: ZMQ_UPSTREAM.
288 Table 8. Summary of ZMQ_PULL characteristics
290 Compatible peer sockets ZMQ_PUSH
291 Direction Unidirectional
293 Send/receive pattern Receive only
295 Incoming routing strategy Fair-queued
297 Outgoing routing strategy N/A
299 ZMQ_HWM option action N/A
301 Exclusive pair pattern
304 The exclusive pair pattern is used to connect a peer to precisely one
305 other peer. This pattern is used for inter-thread communication across
306 the inproc transport.
307 ZMQ_PAIR
309 A socket of type ZMQ_PAIR can only be connected to a single peer at
310 any one time. No message routing or filtering is performed on
311 messages sent over a ZMQ_PAIR socket.
312 When a ZMQ_PAIR socket enters an exceptional state due to having
314 reached the high water mark for the connected peer, or if no peer
315 is connected, then any zmq_send(3) operations on the socket shall
316 block until the peer becomes available for sending; messages are
317 not discarded.
318 Note
320 ZMQ_PAIR sockets are designed for inter-thread communication
321 across the zmq_inproc(7) transport and do not implement
322 functionality such as auto-reconnection. ZMQ_PAIR sockets are
323 considered experimental and may have other missing or broken
324 aspects.
325 Table 9. Summary of ZMQ_PAIR characteristics
327 Compatible peer sockets ZMQ_PAIR
328 Direction Bidirectional
330 Send/receive pattern Unrestricted
333 Incoming routing strategy N/A
335 Outgoing routing strategy N/A
337 ZMQ_HWM option action Block
339
342 The zmq_socket() function shall return an opaque handle to the newly
343 created socket if successful. Otherwise, it shall return NULL and set
344 errno to one of the values defined below.
345
347 EINVAL
348 The requested socket type is invalid.
349 EFAULT
351 The provided context was not valid (NULL).
352 ETERM
354 The context specified was terminated.
355
357 zmq_init(3) zmq_setsockopt(3) zmq_bind(3) zmq_connect(3) zmq_send(3)
358 zmq_recv(3) zmq_inproc(7) zmq(7)
359
361 This 0MQ manual page was written by Martin Sustrik
362 <sustrik@250bpm.com[1]> and Martin Lucina <mato@kotelna.sk[2]>.
363
365 1. sustrik@250bpm.com
366 mailto:sustrik@250bpm.com
367 2. mato@kotelna.sk
369 mailto:mato@kotelna.sk
3700MQ 2.1.4 03/30/2011 ZMQ_SOCKET(3)