diff options
Diffstat (limited to 'doc/zmq_setsockopt.txt')
| -rw-r--r-- | doc/zmq_setsockopt.txt | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt new file mode 100644 index 0000000..549a2de --- /dev/null +++ b/doc/zmq_setsockopt.txt @@ -0,0 +1,155 @@ +zmq_setsockopt(3) +================= + + +NAME +---- + +zmq_setsockopt - sets a specified option on a 0MQ socket + + +SYNOPSIS +-------- +'int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);' + + +DESCRIPTION +----------- +Sets an option on the socket. 'option' argument specifies the option from the +list below. 'optval' is a pointer to the value to set, 'optvallen' is the size +of the value in bytes. + +*ZMQ_HWM*:: +High watermark for the message pipes associated with the socket. The water +mark cannot be exceeded. If the messages don't fit into the pipe emergency +mechanisms of the particular socket type are used (block, drop etc.) If HWM +is set to zero, there are no limits for the content of the pipe. ++ +Type: int64_t Unit: messages Default: 0 + +*ZMQ_LWM*:: +Low watermark makes sense only if high watermark is defined (i.e. is non-zero). +When the emergency state is reached when messages overflow the pipe, the +emergency lasts at most till the size of the pipe decreases to low watermark. +Normal state is resumed at that point. ++ +Type: int64_t Unit: messages Default: 0 + +*ZMQ_SWAP*:: +Swap allows the pipe to exceed high watermark. However, the data are written +to the disk rather than held in the memory. Until high watermark is +exceeded there is no disk activity involved though. The value of the option +defines maximal size of the swap file. ++ +Type: int64_t Unit: bytes Default: 0 + +*ZMQ_AFFINITY*:: +Affinity defines which threads in the thread pool will be used to handle +newly created sockets. This way you can dedicate some of the threads (CPUs) +to a specific work. Value of 0 means no affinity. Work is distributed +fairly among the threads in the thread pool. For non-zero values, the lowest +bit corresponds to the thread 1, second lowest bit to the thread 2 etc. +Thus, value of 3 means that from now on newly created sockets will handle +I/O activity exclusively using threads no. 1 and 2. ++ +Type: int64_t Unit: N/A (bitmap) Default: 0 + +*ZMQ_IDENTITY*:: +Identity of the socket. Identity is important when restarting applications. +If the socket has no identity, each run of the application is completely +separated from other runs. However, with identity application reconnects to +existing infrastructure left by the previous run. Thus it may receive +messages that were sent in the meantime, it shares pipe limits with the +previous run etc. ++ +Type: string Unit: N/A Default: NULL + +*ZMQ_SUBSCRIBE*:: +Applicable only to ZMQ_SUB socket type. It establishes new message filter. +When ZMQ_SUB socket is created all the incoming messages are filtered out. +This option allows you to subscribe for all messages (""), or messages +beginning with specific prefix (e.g. "animals.mammals.dogs."). Multiple +filters can be attached to a single 'sub' socket. In that case message passes +if it matches at least one of the filters. ++ +Type: string Unit: N/A Default: N/A + +*ZMQ_UNSUBSCRIBE*:: +Applicable only to ZMQ_SUB socket type. Removes existing message filter. +The filter specified must match the string passed to ZMQ_SUBSCRIBE options +exactly. If there were several instances of the same filter created, +this options removes only one of them, leaving the rest in place +and functional. ++ +Type: string Unit: N/A Default: N/A + +*ZMQ_RATE*:: +This option applies only to sending side of multicast transports (pgm & udp). +It specifies maximal outgoing data rate that an individual sender socket +can send. ++ +Type: uint64_t Unit: kilobits/second Default: 100 + +*ZMQ_RECOVERY_IVL*:: +This option applies only to multicast transports (pgm & udp). It specifies +how long can the receiver socket survive when the sender is inaccessible. +Keep in mind that large recovery intervals at high data rates result in +very large recovery buffers, meaning that you can easily overload your box +by setting say 1 minute recovery interval at 1Gb/s rate (requires +7GB in-memory buffer). ++ +Type: uint64_t Unit: seconds Default: 10 + +*ZMQ_MCAST_LOOP*:: +This option applies only to multicast transports (pgm & udp). Value of 1 +means that the mutlicast packets can be received on the box they were sent +from. Setting the value to 0 disables the loopback functionality which +can have negative impact on the performance. If possible, disable +the loopback in production environments. ++ +Type: uint64_t Unit: N/A (boolean value) Default: 1 + +*ZMQ_SNDBUF*:: +Sets the underlying kernel transmit buffer size to the specified size. See +'SO_SNDBUF' POSIX socket option. Value of zero means leaving the OS default +unchanged. ++ +Type: uint64_t Unit: bytes Default: 0 + +*ZMQ_RCVBUF*:: +Sets the underlying kernel receive buffer size to the specified size. See +'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default +unchanged. ++ +Type: uint64_t Unit: bytes Default: 0 + + +RETURN VALUE +------------ +In case of success the function returns zero. Otherwise it returns -1 and +sets 'errno' to the appropriate value. + + +ERRORS +------ +*EINVAL*:: +unknown option, a value with incorrect length or invalid value. + + +EXAMPLE +------- +---- +int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "", 0); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHOR +------ +Martin Sustrik <sustrik at 250bpm dot com> |