1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
'\" t
.\" Title: zmq_device
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 07/01/2011
.\" Manual: 0MQ Manual
.\" Source: 0MQ 2.1.8
.\" Language: English
.\"
.TH "ZMQ_DEVICE" "3" "07/01/2011" "0MQ 2\&.1\&.8" "0MQ Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
zmq_device \- start built\-in 0MQ device
.SH "SYNOPSIS"
.sp
\fBint zmq_device (int \fR\fB\fIdevice\fR\fR\fB, const void \fR\fB\fI*frontend\fR\fR\fB, const void \fR\fB\fI*backend\fR\fR\fB);\fR
.SH "DESCRIPTION"
.sp
The \fIzmq_device()\fR function starts a built\-in 0MQ device\&. The \fIdevice\fR argument is one of:
.PP
\fIZMQ_QUEUE\fR
.RS 4
starts a queue device
.RE
.PP
\fIZMQ_FORWARDER\fR
.RS 4
starts a forwarder device
.RE
.PP
\fIZMQ_STREAMER\fR
.RS 4
starts a streamer device
.RE
.sp
The device connects a frontend socket to a backend socket\&. Conceptually, data flows from frontend to backend\&. Depending on the socket types, replies may flow in the opposite direction\&.
.sp
Before calling \fIzmq_device()\fR you must set any socket options, and connect or bind both frontend and backend sockets\&. The two conventional device models are:
.PP
\fBproxy\fR
.RS 4
bind frontend socket to an endpoint, and connect backend socket to downstream components\&. A proxy device model does not require changes to the downstream topology but that topology is static (any changes require reconfiguring the device)\&.
.RE
.PP
\fBbroker\fR
.RS 4
bind frontend socket to one endpoint and bind backend socket to a second endpoint\&. Downstream components must now connect into the device\&. A broker device model allows a dynamic downstream topology (components can come and go at any time)\&.
.RE
.sp
\fIzmq_device()\fR runs in the current thread and returns only if/when the current context is closed\&.
.SH "QUEUE DEVICE"
.sp
\fIZMQ_QUEUE\fR creates a shared queue that collects requests from a set of clients, and distributes these fairly among a set of services\&. Requests are fair\-queued from frontend connections and load\-balanced between backend connections\&. Replies automatically return to the client that made the original request\&.
.sp
This device is part of the \fIrequest\-reply\fR pattern\&. The frontend speaks to clients and the backend speaks to services\&. You should use \fIZMQ_QUEUE\fR with a \fIZMQ_XREP\fR socket for the frontend and a \fIZMQ_XREQ\fR socket for the backend\&. Other combinations are not documented\&.
.sp
Refer to \fBzmq_socket\fR(3) for a description of these socket types\&.
.SH "FORWARDER DEVICE"
.sp
\fIZMQ_FORWARDER\fR collects messages from a set of publishers and forwards these to a set of subscribers\&. You will generally use this to bridge networks, e\&.g\&. read on TCP unicast and forward on multicast\&.
.sp
This device is part of the \fIpublish\-subscribe\fR pattern\&. The frontend speaks to publishers and the backend speaks to subscribers\&. You should use \fIZMQ_FORWARDER\fR with a \fIZMQ_SUB\fR socket for the frontend and a \fIZMQ_PUB\fR socket for the backend\&. Other combinations are not documented\&.
.sp
Refer to \fBzmq_socket\fR(3) for a description of these socket types\&.
.SH "STREAMER DEVICE"
.sp
\fIZMQ_STREAMER\fR collects tasks from a set of pushers and forwards these to a set of pullers\&. You will generally use this to bridge networks\&. Messages are fair\-queued from pushers and load\-balanced to pullers\&.
.sp
This device is part of the \fIpipeline\fR pattern\&. The frontend speaks to pushers and the backend speaks to pullers\&. You should use \fIZMQ_STREAMER\fR with a \fIZMQ_PULL\fR socket for the frontend and a \fIZMQ_PUSH\fR socket for the backend\&. Other combinations are not documented\&.
.sp
Refer to \fBzmq_socket\fR(3) for a description of these socket types\&.
.SH "RETURN VALUE"
.sp
The \fIzmq_device()\fR function always returns \-1 and \fIerrno\fR set to \fBETERM\fR (the 0MQ \fIcontext\fR associated with either of the specified sockets was terminated)\&.
.SH "EXAMPLE"
.PP
\fBCreating a queue broker\fR.
.sp
.if n \{\
.RS 4
.\}
.nf
// Create frontend and backend sockets
void *frontend = zmq_socket (context, ZMQ_XREP);
assert (backend);
void *backend = zmq_socket (context, ZMQ_XREQ);
assert (frontend);
// Bind both sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
// Start a queue device
zmq_device (ZMQ_QUEUE, frontend, backend);
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.sp
\fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_socket\fR(3) \fBzmq\fR(7)
.SH "AUTHORS"
.sp
This 0MQ manual page was written by Pieter Hintjens <\m[blue]\fBph@imatix\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "RESOURCES"
.sp
Main web site: \m[blue]\fBhttp://www\&.zeromq\&.org/\fR\m[]
.sp
Report bugs to the 0MQ development mailing list: <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[2]\d\s+2>
.SH "COPYING"
.sp
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\&.
.SH "NOTES"
.IP " 1." 4
ph@imatix.com
.RS 4
\%mailto:ph@imatix.com
.RE
.IP " 2." 4
zeromq-dev@lists.zeromq.org
.RS 4
\%mailto:zeromq-dev@lists.zeromq.org
.RE
|
