ZeroMQ接口函数之 ：zmq_setsockopt –设置ZMQ socket的属性

标签：

ZeroMQ API 目录 ：http://www.cnblogs.com/fengbohello/p/4230135.html

ZeroMQ 官方地址 ：http://api.zeromq.org/4-0:zmq_setsockopt

本文地址 ：http://www.cnblogs.com/fengbohello/p/4398953.html

翻译：郝峰波

mail : fengbohello@qq.com

zmq_setsockopt(3)         ØMQ Manual - ØMQ/4.1.0

Name

zmq_setsockopt –设置ZMQ socket的属性

Synopsis

int zmq_setsockopt (void *socket, int option_name, const void *option_value, size_t option_len);

注意：除了以下属性，所有的属性均需要在对socket进行bind/connect操作之前设置：
ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE, ZMQ_LINGER, ZMQ_ROUTER_HANDOVER,
ZMQ_ROUTER_MANDATORY, ZMQ_PROBE_ROUTER, ZMQ_XPUB_VERBOSE, ZMQ_REQ_CORRELATE, and ZMQ_REQ_RELAXED

特别的，安全的属性也可以在bind/connect操作之后生效，并且可以随时进行修改并影响之后的bind/connect操作。

Description

zmq_setsockopt()函数会对socket参数指定的socket进行设置，设置的属性由option_name参数指定，属性值由参数option_value指定。option_len参数指定属性值的数据存储空间的大小。

以下的socket属性可以通过zmq_setsockopt()函数进行设置：

ZMQ_SNDHWM：对向外发送的消息设置高水位（最大缓存量）

ZMQ_SNDHWM属性将会设置socket参数指定的socket对外发送的消息的高水位。高水位是一个硬限制，它会限制每一个与此socket相连的在内存中排队的未处理的消息数目的最大值。0值代表着没有限制。

如果已经到达了规定的限制，socket就需要进入一种异常的状态，表现形式因socket类型而异。socket会进行适当的调节，比如阻塞或者丢弃已发送的消息。请从zmq_socket(3)函数中查看更多细节，获取每种类型的socket的精确的行为。

ZMQ并不能保证可以接收像ZMQ_SNDHWM参数一样多的消息，而实际的限制可能在60~70%一下，这取决于这个socket上的消息流。

ZMQ_RCVHWM：对进入socket的消息设置高水位

ZMQ_RCVHWM属性将会设置socket参数指定的socket进入的消息的高水位。高水位是一个硬限制，它会限制每一个与此socket相连的在内存中排队的未处理的消息数目的最大值。0值代表着没有限制。

如果已经到达了规定的限制，socket就需要进入一种异常的状态，表现形式因socket类型而异。socket会进行适当的调节，比如阻塞或者丢弃被发送的消息。请从zmq_socket(3)函数中查看更多细节，获取每种类型的socket的精确的行为。

ZMQ_AFFINITY：设置I/O线程关联

ZMQ_AFFINITY属性会对socket参数指定的socket新创建的链接设置I/O线程关联。

关联指明了和scoket相关的context上的哪个线程池中的哪个线程来处理新创建的链接。0值表示没有关联，这意味着工作将在线程池中平等的向所有进程进行分发。对于非0值，最低位对应线程1，第二低位对应线程2,等等。比如，设置的值是3的话，说明socket上这之后的链接请求将被I/P线程1和2处理。

请参见zmq_init(3)函数了解更多关于对I/O线程分配的细节。

ZMQ_SUBSCRIBE：创建消息过滤标志

ZMQ_SUBSCRIBE属性将会在ZMQ_SUB类型的socekt上创建一个新的消息过滤标志。新建立的ZMQ_SUB类型socket会对进入socket的所有消息进行过滤，这样你就可以使用这个属性来建立最初的消息过滤项。

一个option_value的长度是0的过滤属性会订阅所有的广播消息。一个非空的option_value值会只订阅所有以option_value的值为前缀的消息。一个ZMQ_SUB类型的socket可以附加多个过滤条件，只要一个消息符合过滤条件中的任何一个就会被接受。

ZMQ_UNSUBSCRIBE：移除消息过滤选项

ZMQ_UNSUBSCRIBE选项会移除一个ZMQ_SUB类型中已经存在的消息过滤项。需要被移除的过滤选项必须是已经使用ZMQ_SUBSCRIBE选项建立了的。如果添加了几个相同的过滤项，ZMQ_UNSUBSCRIBE选项只会移除其中的一个，其它的可以继续使用。

ZMQ_IDENTITY：设置socket 身份ID

ZMQ_IDENTITY选项会设置socket的身份ID。socket的身份ID只会能在请求/回复模式中使用。也就是说，可以使用ROUTER类型的socket进行socket串联，根据给定的身份ID可以对消息进行路由。

身份ID至少有1 B的长度，最多有255 B的长度。以0位开始的身份ID由ZMQ保留使用。

如果两个socket使用相同的身份ID向第三方进行连接，后果是不确定的。

ZMQ_RATE：设置广播数据的频率

ZMQ_RATE属性会对socket的接收和发送广播（比如zmq_pgm()）的频率最大值进行设置。

ZMQ_RECOVERY_IVL：设置多路广播恢复时间

ZMQ_RECOVERY_IVL属性将会对socket参数指定的socket多路广播恢复时间进行设置。恢复时间决定了，当一个接收端从一个广播组退出后再连接上来之前，在数据丢失，导致数据不可恢复前的最大时间间隔，时间以毫秒为单位。

注意：当设置较大的恢复时间时，这回非常耗内存。比如，传输速率是1Gbps时，1分钟长的回复时间，会导致7GB的内存消耗。

ZMQ_SNDBUF：设置内核传输缓冲区大小

ZMQ_SNDBUF属性会对socekt参数指定的socket设置底层内核的传输缓存大小，以B为单位进行设置。设置的属性值是0，则意味着使用OS的默认值。你可以查看你的操作系统手册来获得SO_SNDBUF属性更详细的信息。

ZMQ_RCVBUF：设置内核传输缓冲区大小

ZMQ_RCVBUF属性会对socekt参数指定的socket设置底层内核的传输缓存大小，以B为单位进行设置。设置的属性值是0，则意味着使用OS的默认值。你可以查看你的操作系统手册来获得SO_RCVBUF属性更详细的信息。

ZMQ_LINGER：为socket关闭设置停留时间

ZMQ_LINGER属性会给指定的socket设定关闭前的停留时间。停留时间指定了在对一个socket调用zmq_close(3)函数之后，这个socekt上即将被发送但还没有被发送到对端的消息在内存中继续停留的时间。这个属性进而还会影响到与这个scoket相关联的context上zmq_term(3)操作的进行终结的结果。下面简述了不同的行为：

属性值 -1表示无限的停留时间。还没被发送的消息在socket调用zmq_close()操作之后不会被丢弃；试图使用zmq_term()操作对context进行终结的操作会被阻塞，直到所有没有被发送的消息被发往对端为止。

属性值0 表示没有停留时间。当使用zmq_close()函数将socket关闭的时候，所有没有被发送呃消息都会被丢弃。

属性是正数值表示设置一个毫秒为单位的停留时间。在第socket调用zmq_close()操作后，还没有发送的消息不会被丢弃；试图使用zmq_term()对于此scoket相关联的context进行终结的时候会被阻塞，直到所有未被发送的消息都被发往对端；或者停留时间已经到达，此时所有未发送的消息都会被丢弃。

ZMQ_RECONNECT_IVL：设置重连间隔

ZMQ_RECONNECT_IVL属性会设置指定的scoket的初始套接字重连间隔。重连间隔是使用面向连接的传输方式的时候，当与对端的链接断开后，尝试再次进行连接时的ZMQ周期。属性值是 -1表示不进行重连。

ZMQ中的重连间隔可能是个随机的较大数值，以防在拓扑结构中重连风暴的发生。

ZMQ_RECONNECT_IVL_MAX：设置重连间隔的最大值

ZMQ_RECONNECT_IVL_MAX属性会设置指定的scoket的重连间隔最大值。这是在ZMQ重连周期之间的最大值。在每次的重连企图中，重连间隔值都会是前一次的两倍，知道达到ZMQ_RECONNECT_IVL_MAX值。这允许指数补偿策略。默认值表示不执行指数补偿策略，并且重连间隔时间只基于ZMQ_RECONNECT_IVL进行计算。

低于ZMQ_RECONNECT_IVL的值将被忽略。

ZMQ_BACKLOG：设置向外发起的连接队列的最大长度

ZMQ_BACKLOG属性会设置指定的socket的每一个向外连接队列的最大长度；这只对面向连接的传输方式起作用。要查看更多细节请查看你的操作系统的文档中listen函数。

ZMQ_MAXMSGSIZE：可接受的最大进入消息的大小

限制进入的消息的大小。如果一端发送了一条消息比ZMQ_MAXMSGSIZE大，就会断开连接。属性值是 -1表示没有限制。

ZMQ_MULTICAST_HOPS：多播数据包时候的最大网络中继

设置从这个socket发送出去的多播数据包的存活时间默认值是1，表示这个多播包不能离开本地网络。

ZMQ_RCVTIMEO：在一个recv操作返回EAGAIN错误前的最大时间

设置socket的接收操作超时时间。如果属性值是0，zmq_recv(3)函数将会立刻返回，如果没有接收到任何消息，将会返回EAGAIN错误。如果属性值是 -1，将会阻塞，直到接收到消息为止。对于任何其它值，都会进行等待这么多时间，直到返回EAGAIN错误。

ZMQ_SNDTIMEO：在一个发送操作返回EAGAIN之前等待的最大时间

设置指定socket的发送超时。如果属性值是0，zmq_send(3)函数会立即返回，如果无法发送此消息，则返回EAGAIN错误值。如果属性值是 -1，那么在消息发送之前会进入阻塞模式。对于所有其它的值，将会在超时时间内进行尝试发送消息，超时后返回EAGAIN错误。

ZMQ_IPV6：在socket上允许使用IPv6

设置此socket的IPv6属性。属性值是1表示IPv6在此socket上可以使用，而属性值是0表示此socket上只能使用IPv4。当socket上允许使用IPv6的时候，这个scoket可以IPv4或者IPv6进行连接或者接受连接。

ZMQ_IPV4ONLY：在socket上只使用IPv4

设置只使用IPv4属性。不赞成使用这个属性。请使用ZMQ_IPV6属性。

ZMQ_IMMEDIATE：队列消息只作用于已完成的链接

默认情况下，消息队列在及时连接没有完全建立的时候也会向外发送消息。这会导致使用循环路由的scoket（REQ，PUSH，DEALER）消息“丢失”。如果属性值设置为1，消息只会在连接已经建立完成的时候才会进行发送。这回导致当另一方没有连接的时候出现阻塞的情况，但是可以防止消息队列在等待连接的时候填充管道。

ZMQ_ROUTER_HANDOVER：处理ROUTER socket上的每一个身份ID名冲突

设置当ROUTER socket遇到同名身份ID时的行为。默认情况下，当两个对顿使用相同的身份ID连接到同一个ROUTER socket上的时候，结果是不确定的。属性值是1表示会使ROUTER scoket遇到身份ID冲突的时候进行身份ID的重新分配。特别的，第一次连接上来的socket将会被中介，而第二次连接上来的socket将会接收接下来所有路由给这个身份ID名的消息。

ZMQ_ROUTER_MANDATORY：在ROUTER socket上只接收可以进行路由的消息

设置ROUTER socket收到无法路由的消息时的行为。默认属性值是0，表示会静默的丢弃不能路由到的消息。属性值是1时，如果消息不能路由，会返回一个EHOSTUNREACH错误代码。

ZMQ_ROUTER_RAW：转换ROUTER socket到原始模式

当设置为1的时候，及把ROUTER 设置为原始模式。当ROUTER为原始模式并且在使用tcp://传输方式的时候，将不会以ZMQ格式读取和写入TCP数据。这就使ZMQ应用程序可以和非ZMQ程序进行交流。当使用原始模式的时候，你不能使用明确的身份ID，并且在发送消息的时候ZMQ_MSGMORE标志也会被忽略。在原始模式下，你可以采用在发送了一个明确的身份ID后，紧跟着发送一个空消息来关闭一个指定的连接。

不建议使用这个选项，请使用ZMQ_STREAM 类型的socket来代替。

ZMQ_PROBE_ROUTER：ROUTER socket 的引导连接

当次属性设置为1的时候，如果有闲的连接建立了或者接受了新的连接，这个scoket就会自动发送一个空的消息。你可以在连接到ROUTER socket的REQ、DEALER或者ROUTER socket上设置这个属性。这些应用程序必须能够区分这个空消息。ZMQ_PROBE_ROUTER属性实际上给ROUTER应用程序提供了一个信号信号，说明一个新的对端活着。

不要在一个向任何socket类型进行会话的socket上设置此属性：结果是未知的。

ZMQ_XPUB_VERBOSE：提供XPUB socket上的所有订阅消息

设置XPUB socket在新的订阅和取消订阅时的行为。默认属性值是0，并且只允许新的订阅消息通过传输到上游。属性值是1表示允许所有的订阅信息通过传输到上游。

ZMQ_REQ_CORRELATE：匹配请求回复

REQ scoket的默认行为是依靠消息的次序进行请求和回复的匹配，并且这种方式一般情况下也是足够用的。当这个属性值设置成1的时候，REQ socket 会在向外发送的消息前面加上一个请求ID帧前缀。这就意味着整个消息的结构是（请求ID，0，用户帧）。REQ socket会丢弃所有不是以这两个帧作为开始的消息。

ZMQ_REQ_RELAXED：放松请求和回复之间严格的轮换

默认情况下，REQ socket 不允许在接收到上一个回复之前使用zmq_send(3)开始一个新的请求。当这个属性值设置为1的时候，会允许发送另一个请求，并且结果是断开与期望回复消息端的底层的链接，在支持重连的传输协议里，会触发一个重连的尝试。请求-回复状态被重置，并且一个新的请求会发送到下一个可用的对端上。

如果设置此属性值为1，应该同时设置ZMQ_REQ_CORRELATE可用，以确保对请求和回复的正确匹配。否则，如果一个已经被断开的链接发来一个迟来的回复，可能会被认作后来的请求的回复。

ZMQ_TCP_KEEPALIVE：代替SO_KEEPALIVE属性

代替了SO_KEEPALIVE属性。默认值是 -1，表示跳过所有的重写操作，并且把这些属性值交给操作系统。

ZMQ_TCP_KEEPALIVE_IDLE：代替TCP_KEEPCNT（有些操作系统上是TCP_KEEPALIVE）属性

代替TCP_KEEPCNT（有些操作系统上是TCP_KEEPALIVE）属性（当操作系统支持的时候）。默认值是 -1，表示跳过所有的重写操作，并且把这些属性值交给操作系统。

ZMQ_TCP_KEEPALIVE_CNT：代替TCP_KEEPCNT socket属性

代替TCP_KEEPCNT socket属性（当操作系统支持的时候）。默认值是 -1，表示跳过所有的重写操作，并且把这些属性值交给操作系统。

ZMQ_TCP_KEEPALIVE_INTVL：代替TCP_KEEPINTVL socket 属性

代替TCP_KEEPINTVL socket 属性（当操作系统支持的时候）。默认值是 -1，表示跳过所有的重写操作，并且把这些属性值交给操作系统。

ZMQ_TCP_ACCEPT_FILTER：为新连上来的TCP连接分配过滤器

在一个监听socket上分配一个任意的过滤器会作用于每一个新连接上来的TCP链接。如果没有使用任何过滤器，TCP传输会允许任意的IP地址连接上来。如果设置了至少一个过滤器，那么新连接上来的源ip就需要能够匹配。向情况所有的过滤器，请调用zmq_setsockopt(socket, ZMQ_TCP_ACCEPT_FILTER, NULL, 0)。过滤器是一个以空字节结尾的IPv6或IPv4 CIDR（无类域间路由）。

ZMQ_PLAIN_SERVER：设置PLAIN 服务的角色

定义一个socket是否作为PLAIN 安全方式的服务端，参见zmq_plain(7)。设置属性值为1表示这个scoket将会作为PLAIN的服务端。属性值设置为0表示这个socket不作为PLAIN服务端，并且它的安全方式依赖于其它的属性设置。设置此属性为0会重置这个scoket的安全方式为NULL。

ZMQ_PLAIN_USERNAME：设置PLAIN安全方式的用户名

设置TCP或者IPC对外连接的用户名。如果你设置这个属性为非空值，用于连接的安全机制会是PLAIN，参见zmq_plain(7)。如果你设置此属性值为空值，用于连接的安全机制会是NULL，参见zmq_null(3)。

ZMQ_PLAIN_PASSWORD：设置PLAIN安全方式的密码

设置TCP或者IPC对外连接的密码。如果你设置这个属性为非空值，用于连接的安全机制会是PLAIN，参见zmq_plain(7)。如果你设置此属性值为空值，用于连接的安全机制会是NULL，参见zmq_null(3)。

ZMQ_CURVE_SERVER：设置CURVE服务端角色

定义一个socket是否为CURVE 安全方式的服务端，参见zmq_curve(7)。属性值是1表示这个 socket将会作为一个CURVE服务端。属性值是0表示这个socket将不会作为CURVE客户端，并且其安全方式的角色将会依赖于其它属性设置。设置此属性值为0将会重置此socket的安全方式为NULL。如果你设置这个属性，你必须使用ZMQ_CURVE_SECRETKEY属性设置这个服务端的秘钥。一个服务端socket不需要知道它自己的公钥。

ZMQ_CURVE_PUBLICKEY：设置CURVE公钥

设置socket的长期公钥。你必须设置CURVE客户端的这个属性，参见zmq_curve(7)。你可以用32位二进制字节或者经过Z85格式加密后的40字符串。这个公钥必须和秘钥匹配使用。可以使用zmq_curve_keypair(3)函数生成一个公钥/密钥对。

ZMQ_CURVE_SECRETKEY：设置CURVE密钥

这是此socket的长期密钥。你必须在CURVE客户端和服务端上都设置此属性，参见zmq_curve(7)。你可以用32位二进制字节或者经过Z85格式加密后的40字符串。这个公钥必须和秘钥匹配使用。可以使用zmq_curve_keypair(3)函数生成一个公钥/密钥对。

ZMQ_CURVE_SERVERKEY：设置CURVE服务端码

设置此socket的长期服务端码。你必须在客户端socket上设置此服务端码，参见zmq_curve(7)。你可以用32位二进制字节或者经过Z85格式加密后的40字符串。这个公钥必须和秘钥匹配使用。这个码必须是服务端生成密钥的时候一块生成的。

ZMQ_ZAP_DOMAIN：设置RFC 27认证域

设置ZAP（ZMQ RFC 27）认证域。对于空的安全方式（默认在所有的tcp://连接上），ZAP认证只在你设置一个非空的域时起作用。对于PLAIN和CURVE安全方式，如果有ZAP处理程序存在，总是会请求ZAP。参见http://rfc.zeromq.org/spec:27 获取更多细节。

ZMQ_CONFLATE：只保留最后到来的消息

如果设置了这个值，socket只会在其入站/出站队列中保留一个消息，那就是最后一个接收到的消息，或者最后一个要发送的消息。设置此属性会忽略ZMQ_RECVHWM属性和ZMQ_SENDHWM属性。不支持多帧消息，特别的，在socket的内部消息队列中，只有一个帧会被保留。

Return value

如果执行成功，zmq_setsockopt()函数会返回0。否则会返回 -1，并且设置errno为下列定义值中的一个。

Errors

　　EINVAL

　　　　请求的属性中，属性名称为止，或者属性长度或者属性值不可用。

　　ETERM

　　　　和指定socket相关的context已经被终结了

　　ENOTSOCK

　　　　参数提供的socket不可用

　　EINTR

　　　　本次操作被信号中断了

Example

　　在一个ZMQ_SUB  socket上设置订阅消息

/* Subscribe to all messages */
rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
assert (rc == 0);
/* Subscribe to messages prefixed with "ANIMALS.CATS" */
 rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);

　　设置I/O线程关联

int64_t affinity;
/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
affinity = 1;
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5555");
assert (rc);
/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
affinity = 2;
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5556"); 
assert (rc);

See also

zmq_getsockopt(3)  zmq_socket(3)  zmq_plain(7)  zmq_curve(7)  zmq(7)

Authors

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

Web site design and content is copyright (c) 2007-2012 iMatix Corporation. Contact us for professional support. Site content licensed under the Creative Commons Attribution-Share Alike 3.0 License. ØMQ is copyright (c) Copyright (c) 2007-2012 iMatix Corporation and Contributors. ØMQ is free software licensed under the LGPL. ØMQ, ZeroMQ, and 0MQ are trademarks of iMatix Corporation. Terms of Use — Privacy Policy

ZeroMQ接口函数之 ：zmq_setsockopt –设置ZMQ socket的属性

标签：

原文地址：http://www.cnblogs.com/fengbohello/p/4398953.html