~ubuntu-branches/ubuntu/precise/zeromq/precise

.\"      Date: 05/07/2011

.\"    Source: 0MQ 2.1.6

.TH "ZMQ_SETSOCKOPT" "3" "05/07/2011" "0MQ 2\&.1\&.6" "0MQ Manual"

.sp

Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE and ZMQ_LINGER, only take effect for subsequent socket bind/connects\&.

The \fIZMQ_IDENTITY\fR option shall set the identity of the specified \fIsocket\fR\&. Socket identity determines if existing 0MQ infrastructure (\fImessage queues\fR, \fIforwarding devices\fR) shall be identified with a specific application and persist across multiple runs of the application\&.

An empty \fIoption_value\fR of length zero shall subscribe to all incoming messages\&. A non\-empty \fIoption_value\fR shall subscribe to all messages beginning with the specified prefix\&. Multiple filters may be attached to a single \fIZMQ_SUB\fR socket, in which case a message shall be accepted if it matches at least one filter\&.

Exercise care when setting large recovery intervals as the data needed for recovery will be held in memory\&. For example, a 1 minute recovery interval at a data rate of 1Gbps requires a 7GB in\-memory buffer\&.

.SS "ZMQ_RECOVERY_IVL_MSEC: Set multicast recovery interval in milliseconds"

.sp

The \fIZMQ_RECOVERY_IVL_MSEC\fR option shall set the recovery interval, specified in milliseconds (ms) for multicast transports using the specified \fIsocket\fR\&. The recovery interval determines the maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur\&.

.sp

A non\-zero value of the \fIZMQ_RECOVERY_IVL_MSEC\fR option will take precedence over the \fIZMQ_RECOVERY_IVL\fR option, but since the default for the \fIZMQ_RECOVERY_IVL_MSEC\fR is \-1, the default is to use the \fIZMQ_RECOVERY_IVL\fR option value\&.

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBCaution\fR

.ps -1

.br

.sp

Exercise care when setting large recovery intervals as the data needed for recovery will be held in memory\&. For example, a 1 minute recovery interval at a data rate of 1Gbps requires a 7GB in\-memory buffer\&.

.sp .5v

.RE

.TS

tab(:);

lt lt

lt lt

lt lt

lt lt.

T{

.sp

Option value type

T}:T{

.sp

int64_t

T}

T{

.sp

Option value unit

T}:T{

.sp

milliseconds

T}

T{

.sp

Default value

T}:T{

.sp

\-1

T}

T{

.sp

Applicable socket types

T}:T{

.sp

all, when using multicast transports

T}

.TE

.sp 1

.SS "ZMQ_MCAST_LOOP: Control multicast loop\-back"

.sp

The \fIZMQ_MCAST_LOOP\fR option shall control whether data sent via multicast transports using the specified \fIsocket\fR can also be received by the sending host via loop\-back\&. A value of zero disables the loop\-back functionality, while the default value of 1 enables the loop\-back functionality\&. Leaving multicast loop\-back enabled when it is not required can have a negative impact on performance\&. Where possible, disable \fIZMQ_MCAST_LOOP\fR in production environments\&.

.SS "ZMQ_LINGER: Set linger period for socket shutdown"

.sp

The \fIZMQ_LINGER\fR option shall set the linger period for the specified \fIsocket\fR\&. The linger period determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with \fBzmq_close\fR(3), and further affects the termination of the socket\(cqs context with \fBzmq_term\fR(3)\&. The following outlines the different behaviours:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

The default value of

\fI\-1\fR

specifies an infinite linger period\&. Pending messages shall not be discarded after a call to

\fIzmq_close()\fR; attempting to terminate the socket\(cqs context with

\fIzmq_term()\fR

shall block until all pending messages have been sent to a peer\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

The value of

\fI0\fR

specifies no linger period\&. Pending messages shall be discarded immediately when the socket is closed with

\fIzmq_close()\fR\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Positive values specify an upper bound for the linger period in milliseconds\&. Pending messages shall not be discarded after a call to

\fIzmq_close()\fR; attempting to terminate the socket\(cqs context with

\fIzmq_term()\fR

shall block until either all pending messages have been sent to a peer, or the linger period expires, after which any pending messages shall be discarded\&.

.TS

tab(:);

lt lt

lt lt

lt lt

lt lt.

T{

Option value type

T}:T{

int

T}

T{

Option value unit

T}:T{

milliseconds

T}

T{

Default value

T}:T{

\-1 (infinite)

T}

T{

Applicable socket types

T}:T{

all

T}

.TE

.sp 1

.RE

.SS "ZMQ_RECONNECT_IVL: Set reconnection interval"

.sp

The \fIZMQ_RECONNECT_IVL\fR option shall set the initial reconnection interval for the specified \fIsocket\fR\&. The reconnection interval is the period 0MQ shall wait between attempts to reconnect disconnected peers when using connection\-oriented transports\&.

.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

The reconnection interval may be randomized by 0MQ to prevent reconnection storms in topologies with a large number of peers per socket\&.

.sp .5v

.RE

.TS

tab(:);

lt lt

lt lt

lt lt

lt lt.

T{

.sp

Option value type

T}:T{

.sp

int

T}

T{

.sp

Option value unit

T}:T{

.sp

milliseconds

T}

T{

.sp

Default value

T}:T{

.sp

100

T}

T{

.sp

Applicable socket types

T}:T{

.sp

all, only for connection\-oriented transports

T}

.TE

.sp 1

.SS "ZMQ_RECONNECT_IVL_MAX: Set maximum reconnection interval"

.sp

The \fIZMQ_RECONNECT_IVL_MAX\fR option shall set the maximum reconnection interval for the specified \fIsocket\fR\&. This is the maximum period 0MQ shall wait between attempts to reconnect\&. On each reconnect attempt, the previous interval shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached\&. This allows for exponential backoff strategy\&. Default value means no exponential backoff is performed and reconnect interval calculations are only based on ZMQ_RECONNECT_IVL\&.

.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

Values less than ZMQ_RECONNECT_IVL will be ignored\&.

.sp .5v

.RE

.TS

tab(:);

lt lt

lt lt

lt lt

lt lt.

T{

.sp

Option value type

T}:T{

.sp

int

T}

T{

.sp

Option value unit

T}:T{

.sp

milliseconds

T}

T{

.sp

Default value

T}:T{

.sp

0 (only use ZMQ_RECONNECT_IVL)

T}

T{

.sp

Applicable socket types

T}:T{

.sp

all, only for connection\-oriented transports

T}

.TE

.sp 1

.SS "ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections"

.sp

The \fIZMQ_BACKLOG\fR option shall set the maximum length of the queue of outstanding peer connections for the specified \fIsocket\fR; this only applies to connection\-oriented transports\&. For details refer to your operating system documentation for the \fIlisten\fR function\&.

.TS

tab(:);

lt lt

lt lt

lt lt

lt lt.

T{

.sp

Option value type

T}:T{

.sp

int

T}

T{

.sp

Option value unit

T}:T{

.sp

connections

T}

T{

.sp

Default value

T}:T{

.sp

100

T}

T{

.sp

Applicable socket types

T}:T{

.sp

all, only for connection\-oriented transports\&.

T}

.TE

.sp 1

\fBENOTSOCK\fR

was invalid\&.

.RE

.PP

\fBEINTR\fR

.RS 4

The operation was interrupted by delivery of a signal\&.

This 0MQ manual page 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>\&.