diff options
Diffstat (limited to 'doc/zmq_device.3')
| -rw-r--r-- | doc/zmq_device.3 | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/doc/zmq_device.3 b/doc/zmq_device.3 new file mode 100644 index 0000000..e19c800 --- /dev/null +++ b/doc/zmq_device.3 @@ -0,0 +1,140 @@ +'\" t +.\" Title: zmq_device +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 03/15/2011 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.1.3 +.\" Language: English +.\" +.TH "ZMQ_DEVICE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "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 |