'\" 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