Imported Upstream version 2.0.7.dfsgupstream/2.0.7.dfsg

1 files changed, 609 insertions, 0 deletions

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 <http://docbook.sf.net/>
+.\"      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