From a15854bd92db69fcd0b4444fe1b8fe3610a7acf6 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:19 +0100 Subject: Imported Upstream version 2.0.7.dfsg --- doc/zmq_socket.3 | 609 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 609 insertions(+) create mode 100644 doc/zmq_socket.3 (limited to 'doc/zmq_socket.3') diff --git a/doc/zmq_socket.3 b/doc/zmq_socket.3 new file mode 100644 index 0000000..3e4ebd1 --- /dev/null +++ b/doc/zmq_socket.3 @@ -0,0 +1,609 @@ +'\" t +.\" Title: zmq_socket +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_SOCKET" "3" "06/04/2010" "0MQ 2\&.0\&.7" "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_socket \- create 0MQ socket +.SH "SYNOPSIS" +.sp +\fBvoid *zmq_socket (void \fR\fB\fI*context\fR\fR\fB, int \fR\fB\fItype\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_socket()\fR function shall create a 0MQ socket within the specified \fIcontext\fR and return an opaque handle to the newly created socket\&. The \fItype\fR argument specifies the socket type, which determines the semantics of communication over the socket\&. +.sp +The newly created socket is initially unbound, and not associated with any endpoints\&. In order to establish a message flow a socket must first be connected to at least one endpoint with \fBzmq_connect\fR(3), or at least one endpoint must be created for accepting incoming connections with \fBzmq_bind\fR(3)\&. +.PP +\fBKey differences to conventional sockets\fR. Generally speaking, conventional sockets present a +\fIsynchronous\fR +interface to either connection\-oriented reliable byte streams (SOCK_STREAM), or connection\-less unreliable datagrams (SOCK_DGRAM)\&. In comparison, 0MQ sockets present an abstraction of an asynchronous +\fImessage queue\fR, with the exact queueing semantics depending on the socket type in use\&. Where conventional sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer discrete +\fImessages\fR\&. +.sp +0MQ sockets being \fIasynchronous\fR means that the timings of the physical connection setup and teardown, reconnect and effective delivery are transparent to the user and organized by 0MQ itself\&. Further, messages may be \fIqueued\fR in the event that a peer is unavailable to receive them\&. +.sp +Conventional sockets allow only strict one\-to\-one (two peers), many\-to\-one (many clients, one server), or in some cases one\-to\-many (multicast) relationships\&. With the exception of \fIZMQ_PAIR\fR, 0MQ sockets may be connected \fBto multiple endpoints\fR using \fIzmq_connect()\fR, while simultaneously accepting incoming connections \fBfrom multiple endpoints\fR bound to the socket using \fIzmq_bind()\fR, thus allowing many\-to\-many relationships\&. +.PP +\fBSocket types\fR. The following sections present the socket types defined by 0MQ, grouped by the general +\fImessaging pattern\fR +which is built from related socket types\&. +.SS "Request\-reply pattern" +.sp +The request\-reply pattern is used for sending requests from a \fIclient\fR to one or more instances of a \fIservice\fR, and receiving subsequent replies to each request sent\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_REQ\fR +.RS 4 +.sp +A socket of type \fIZMQ_REQ\fR is used by a \fIclient\fR to send requests to and receive replies from a \fIservice\fR\&. This socket type allows only an alternating sequence of \fIzmq_send(request)\fR and subsequent \fIzmq_recv(reply)\fR calls\&. Each request sent is load\-balanced among all \fIservices\fR, and each reply received is matched with the last issued request\&. +.sp +When a \fIZMQ_REQ\fR socket enters an exceptional state due to having reached the high water mark for all \fIservices\fR, or if there are no \fIservices\fR at all, then any \fBzmq_send\fR(3) operations on the socket shall block until the exceptional state ends or at least one \fIservice\fR becomes available for sending; messages are not discarded\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Summary of ZMQ_REQ characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_REP\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send, Receive, Send, Receive, \&... +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Load\-balanced +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Last peer +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_REP\fR +.RS 4 +.sp +A socket of type \fIZMQ_REP\fR is used by a \fIservice\fR to receive requests from and send replies to a \fIclient\fR\&. This socket type allows only an alternating sequence of \fIzmq_recv(request)\fR and subsequent \fIzmq_send(reply)\fR calls\&. Each request received is fair\-queued from among all \fIclients\fR, and each reply sent is routed to the \fIclient\fR that issued the last request\&. +.sp +When a \fIZMQ_REP\fR socket enters an exceptional state due to having reached the high water mark for a \fIclient\fR, then any replies sent to the \fIclient\fR in question shall be dropped until the exceptional state ends\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Summary of ZMQ_REP characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_REQ\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive, Send, Receive, Send, \&... +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing stratagy +T}:T{ +.sp +Last peer +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Drop +T} +.TE +.sp 1 +.RE +.SS "Publish\-subscribe pattern" +.sp +The publish\-subscribe pattern is used for one\-to\-many distribution of data from a single \fIpublisher\fR to multiple \fIsubscribers\fR in a fanout fashion\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_PUB\fR +.RS 4 +.sp +A socket of type \fIZMQ_PUB\fR is used by a \fIpublisher\fR to distribute data\&. Messages sent are distributed in a fanout fashion to all connected peers\&. The \fBzmq_recv\fR(3) function is not implemented for this socket type\&. +.sp +When a \fIZMQ_PUB\fR socket enters an exceptional state due to having reached the high water mark for a \fIsubscriber\fR, then any messages that would be sent to the \fIsubscriber\fR in question shall instead be dropped until the exceptional state ends\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Summary of ZMQ_PUB characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_SUB\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Fanout +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Drop +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_SUB\fR +.RS 4 +.sp +A socket of type \fIZMQ_SUB\fR is used by a \fIsubscriber\fR to subscribe to data distributed by a \fIpublisher\fR\&. Initially a \fIZMQ_SUB\fR socket is not subscribed to any messages, use the \fIZMQ_SUBSCRIBE\fR option of \fBzmq_setsockopt\fR(3) to specify which messages to subscribe to\&. The \fIzmq_send()\fR function is not implemented for this socket type\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&4.\ \&Summary of ZMQ_SUB characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_PUB\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.RE +.SS "Pipeline pattern" +.sp +The pipeline pattern is used for distributing data to \fInodes\fR arranged in a pipeline\&. Data always flows down the pipeline, and each stage of the pipeline is connected to at least one \fInode\fR\&. When a pipeline stage is connected to multiple \fInodes\fR data is load\-balanced among all connected \fInodes\fR\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_DOWNSTREAM\fR +.RS 4 +.sp +A socket of type \fIZMQ_DOWNSTREAM\fR is used by a pipeline \fInode\fR to send messages to downstream pipeline \fInodes\fR\&. Messages are load\-balanced to all connected downstream \fInodes\fR\&. The \fIzmq_recv()\fR function is not implemented for this socket type\&. +.sp +When a \fIZMQ_DOWNSTREAM\fR socket enters an exceptional state due to having reached the high water mark for all downstream \fInodes\fR, or if there are no downstream \fInodes\fR at all, then any \fBzmq_send\fR(3) operations on the socket shall block until the exceptional state ends or at least one downstream \fInode\fR becomes available for sending; messages are not discarded\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&5.\ \&Summary of ZMQ_DOWNSTREAM characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_UPSTREAM\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Load\-balanced +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_UPSTREAM\fR +.RS 4 +.sp +A socket of type \fIZMQ_UPSTREAM\fR is used by a pipeline \fInode\fR to receive messages from upstream pipeline \fInodes\fR\&. Messages are fair\-queued from among all connected upstream \fInodes\fR\&. The \fIzmq_send()\fR function is not implemented for this socket type\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&6.\ \&Summary of ZMQ_UPSTREAM characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_DOWNSTREAM\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.RE +.SS "Exclusive pair pattern" +.sp +The exclusive pair is an advanced pattern used for communicating exclusively between two peers\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_PAIR\fR +.RS 4 +.sp +A socket of type \fIZMQ_PAIR\fR can only be connected to a single peer at any one time\&. No message routing or filtering is performed on messages sent over a \fIZMQ_PAIR\fR socket\&. +.sp +When a \fIZMQ_PAIR\fR socket enters an exceptional state due to having reached the high water mark for the connected peer, or if no peer is connected, then any \fBzmq_send\fR(3) operations on the socket shall block until the peer becomes available for sending; messages are not discarded\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +\fIZMQ_PAIR\fR sockets are experimental, and are currently missing several features such as auto\-reconnection\&. +.sp .5v +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&7.\ \&Summary of ZMQ_PAIR characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_PAIR\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Unrestricted +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_socket()\fR function shall return an opaque handle to the newly created socket if successful\&. Otherwise, it shall return NULL and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEINVAL\fR +.RS 4 +The requested socket +\fItype\fR +is invalid\&. +.RE +.PP +\fBEMTHREAD\fR +.RS 4 +The maximum number of sockets within this +\fIcontext\fR +has been exceeded\&. +.RE +.SH "SEE ALSO" +.sp +\fBzmq_init\fR(3) \fBzmq_setsockopt\fR(3) \fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_send\fR(3) \fBzmq_recv\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE -- cgit v1.2.3