Module: CZTop::ZsockOptions

Includes:
CZMQ::FFI
Included in:
Socket
Defined in:
lib/cztop/zsock_options.rb

Overview

Note:

Most socket options only take effect for subsequent bind/connects.

This module adds the ability to access options of a Socket.

See Also:

Constant Summary collapse

POLLIN =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

1
POLLOUT = 
2

Constants included from CZMQ::FFI

CZMQ::FFI::CZMQ_VERSION, CZMQ::FFI::ZFRAME_DONTWAIT, CZMQ::FFI::ZFRAME_MORE, CZMQ::FFI::ZMONITOR_FN, CZMQ::FFI::ZMQ_VERSION

High Water Marks collapse

Send and Receive Timeouts collapse

TCP Keepalive collapse

Instance Method Summary collapse

Instance Method Details

#conflate=(bool) ⇒ Object

Note:

Must be set before connecting/binding.

When true, the socket keeps only the last message in its inbound/outbound queue, discarding older messages. Useful for "last value cache" semantics in PUB/SUB or PUSH/PULL pipelines where only the latest value matters.

Parameters:

  • bool (Boolean) —

    whether to enable conflate mode



376
377
378
379
 
# File 'lib/cztop/zsock_options.rb', line 376

def conflate=(bool)
  Zsock.set_conflate(self, bool ? 1 : 0)
  @conflate = bool
end

#conflate? ⇒ Boolean

Note:

There is no libzmq getter for this option, so the value is tracked locally.

Returns whether conflate mode is enabled.

Returns:

  • (Boolean) —

    whether conflate mode is enabled



363
364
365
 
# File 'lib/cztop/zsock_options.rb', line 363

def conflate?
  !!@conflate
end

#fd ⇒ Integer

Useful for registration in an event-loop.

Returns:

  • (Integer) 


41
42
43
 
# File 'lib/cztop/zsock_options.rb', line 41

def fd
  Zsock.fd(self)
end

#heartbeat_ivl ⇒ Numeric

Returns current value of Heartbeat IVL in seconds.

Returns:

  • (Numeric) —

    current value of Heartbeat IVL in seconds



182
183
184
 
# File 'lib/cztop/zsock_options.rb', line 182

def heartbeat_ivl
  Zsock.heartbeat_ivl(self) / 1000.0
end

#heartbeat_ivl=(new_value) ⇒ Object

Parameters:

  • new_value (Numeric) —

    new value for Heartbeat IVL in seconds

Raises:

  • (ArgumentError) 


189
190
191
192
193
 
# File 'lib/cztop/zsock_options.rb', line 189

def heartbeat_ivl=(new_value)
  raise ArgumentError, 'invalid IVL' unless new_value >= 0

  Zsock.set_heartbeat_ivl(self, (new_value * 1000).to_i)
end

#heartbeat_timeout ⇒ Numeric?

Returns the heartbeat timeout in seconds, or nil if not explicitly set. When nil, libzmq uses #heartbeat_ivl as the timeout (i.e. -1 in the raw option means "use IVL").

Returns:

  • (Numeric, nil) —

    timeout in seconds, or nil if unset



222
223
224
225
 
# File 'lib/cztop/zsock_options.rb', line 222

def heartbeat_timeout
  value = Zsock.heartbeat_timeout(self)
  value == -1 ? nil : value / 1000.0
end

#heartbeat_timeout=(new_value) ⇒ Object

Parameters:

  • new_value (Numeric, nil) —

    new value for Heartbeat Timeout in seconds, or nil to reset to default (use #heartbeat_ivl)

Raises:

  • (ArgumentError) 


231
232
233
234
235
236
237
238
239
240
 
# File 'lib/cztop/zsock_options.rb', line 231

def heartbeat_timeout=(new_value)
  if new_value.nil?
    Zsock.set_heartbeat_timeout(self, 0)
    return
  end

  raise ArgumentError, 'invalid timeout' unless new_value >= 0

  Zsock.set_heartbeat_timeout(self, (new_value * 1000).to_i)
end

#heartbeat_ttl ⇒ Numeric

Returns current value of Heartbeat TTL in seconds.

Returns:

  • (Numeric) —

    current value of Heartbeat TTL in seconds



198
199
200
 
# File 'lib/cztop/zsock_options.rb', line 198

def heartbeat_ttl
  Zsock.heartbeat_ttl(self) / 1000.0
end

#heartbeat_ttl=(new_value) ⇒ Object

Note:

The value will internally be rounded to the nearest decisecond. So a value of less than 0.1 will have no effect.

Parameters:

  • new_value (Numeric) —

    new value for Heartbeat TTL in seconds

Raises:

  • (ArgumentError) 


207
208
209
210
211
212
213
 
# File 'lib/cztop/zsock_options.rb', line 207

def heartbeat_ttl=(new_value)
  raise ArgumentError, "invalid TTL: #{new_value}" unless new_value.is_a? Numeric
  ms = (new_value * 1000).to_i
  raise ArgumentError, "TTL out of range: #{new_value}" unless (0..65_536).include? ms

  Zsock.set_heartbeat_ttl(self, ms)
end

#identity ⇒ String

Returns current socket identity.

Returns:

  • (String) —

    current socket identity



147
148
149
 
# File 'lib/cztop/zsock_options.rb', line 147

def identity
  Zsock.identity(self).read_string
end

#identity=(identity) ⇒ Object

Parameters:

  • identity (String) —

    new socket identity

Raises:

  • (ArgumentError) —

    if identity is invalid



155
156
157
158
159
160
161
 
# File 'lib/cztop/zsock_options.rb', line 155

def identity=(identity)
  raise ArgumentError, 'zero-length identity' if identity.bytesize.zero?
  raise ArgumentError, 'identity too long' if identity.bytesize > 255
  raise ArgumentError, 'invalid identity' if identity.start_with? "\0"

  Zsock.set_identity(self, identity)
end

#immediate=(bool) ⇒ Object

When true, the socket queues messages only for completed connections (i.e. peers that have finished the ZMTP handshake). When false (default), messages may be queued for connections that haven't completed yet, risking message loss if the peer never connects.

Parameters:

  • bool (Boolean) —

    whether to enable immediate mode



354
355
356
 
# File 'lib/cztop/zsock_options.rb', line 354

def immediate=(bool)
  Zsock.set_immediate(self, bool ? 1 : 0)
end

#immediate? ⇒ Boolean

Returns whether the socket queues messages only for completed connections.

Returns:

  • (Boolean) —

    whether the socket queues messages only for completed connections



342
343
344
 
# File 'lib/cztop/zsock_options.rb', line 342

def immediate?
  Zsock.immediate(self) == 1
end

#ipv6=(new_value) ⇒ Object

Set the IPv6 option for the socket. A value of true means IPv6 is enabled on the socket, while false means the socket will use only IPv4. When IPv6 is enabled the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts. Default is false.

Parameters:

  • new_value (Boolean) —

    new value for ipv6



277
278
279
 
# File 'lib/cztop/zsock_options.rb', line 277

def ipv6=(new_value)
  Zsock.set_ipv6(self, new_value ? 1 : 0)
end

#ipv6? ⇒ Boolean

Returns current value of ipv6.

Returns:

  • (Boolean) —

    current value of ipv6



265
266
267
 
# File 'lib/cztop/zsock_options.rb', line 265

def ipv6?
  Zsock.ipv6(self) != 0
end

#linger ⇒ Numeric?

Returns linger period in seconds, or nil to wait indefinitely. 0 means no waiting (default).

Returns:

  • (Numeric, nil) —

    linger period in seconds, or nil to wait indefinitely. 0 means no waiting (default).



246
247
248
249
 
# File 'lib/cztop/zsock_options.rb', line 246

def linger
  value = Zsock.linger(self)
  value == -1 ? nil : value / 1000.0
end

#linger=(new_value) ⇒ Object

Sets how long to wait while closing/disconnecting a socket if there are outstanding messages to send.

Parameters:

  • new_value (Numeric, nil) —

    linger period in seconds, or nil to wait indefinitely. 0 means no waiting (default).



258
259
260
 
# File 'lib/cztop/zsock_options.rb', line 258

def linger=(new_value)
  Zsock.set_linger(self, new_value.nil? ? -1 : (new_value * 1000).to_i)
end

#max_msg_size ⇒ Integer?

Returns maximum inbound message size in bytes, or nil if unlimited (the default, -1 in libzmq).

Returns:

  • (Integer, nil) —

    maximum inbound message size in bytes, or nil if unlimited (the default, -1 in libzmq)



323
324
325
326
 
# File 'lib/cztop/zsock_options.rb', line 323

def max_msg_size
  value = Zsock.maxmsgsize(self)
  value == -1 ? nil : value
end

#max_msg_size=(new_value) ⇒ Object

Sets the maximum inbound message size. Messages larger than this are dropped and the connection is disconnected. Useful for DoS protection.

Parameters:

  • new_value (Integer, nil) —

    max size in bytes, or nil for unlimited



334
335
336
 
# File 'lib/cztop/zsock_options.rb', line 334

def max_msg_size=(new_value)
  Zsock.set_maxmsgsize(self, new_value.nil? ? -1 : new_value)
end

#rcvhwm ⇒ Integer

Returns the receive high water mark.

Returns:

  • (Integer) —

    the receive high water mark



71
72
73
 
# File 'lib/cztop/zsock_options.rb', line 71

def rcvhwm
  Zsock.rcvhwm(self)
end

#rcvhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new receive high water mark



78
79
80
 
# File 'lib/cztop/zsock_options.rb', line 78

def rcvhwm=(value)
  Zsock.set_rcvhwm(self, value)
end

#readable? ⇒ Boolean

Checks whether there's a message that can be read from the socket without blocking.

Returns:

  • (Boolean) —

    whether the socket is readable



24
25
26
 
# File 'lib/cztop/zsock_options.rb', line 24

def readable?
  (events & POLLIN).positive?
end

#reconnect_ivl ⇒ Numeric?

Returns reconnect interval in seconds, or nil if reconnection is disabled.

Returns:

  • (Numeric, nil) —

    reconnect interval in seconds, or nil if reconnection is disabled



285
286
287
288
 
# File 'lib/cztop/zsock_options.rb', line 285

def reconnect_ivl
  value = Zsock.reconnect_ivl(self)
  value == -1 ? nil : value / 1000.0
end

#reconnect_ivl=(new_value) ⇒ Object

Parameters:

  • new_value (Numeric, nil) —

    reconnect interval in seconds, or nil to disable reconnection



294
295
296
 
# File 'lib/cztop/zsock_options.rb', line 294

def reconnect_ivl=(new_value)
  Zsock.set_reconnect_ivl(self, new_value.nil? ? -1 : (new_value * 1000).to_i)
end

#reconnect_ivl_max ⇒ Numeric?

Returns maximum reconnect interval in seconds, or nil if no maximum is set (uses fixed #reconnect_ivl).

Returns:

  • (Numeric, nil) —

    maximum reconnect interval in seconds, or nil if no maximum is set (uses fixed #reconnect_ivl)



302
303
304
305
 
# File 'lib/cztop/zsock_options.rb', line 302

def reconnect_ivl_max
  value = Zsock.reconnect_ivl_max(self)
  value.zero? ? nil : value / 1000.0
end

#reconnect_ivl_max=(new_value) ⇒ Object

Sets the maximum reconnect interval for exponential backoff. When set, reconnect intervals grow from #reconnect_ivl up to this maximum. Set to nil to disable backoff (use fixed interval).

Parameters:

  • new_value (Numeric, nil) —

    max reconnect interval in seconds, or nil to disable backoff



315
316
317
 
# File 'lib/cztop/zsock_options.rb', line 315

def reconnect_ivl_max=(new_value)
  Zsock.set_reconnect_ivl_max(self, new_value.nil? ? 0 : (new_value * 1000).to_i)
end

#recv_timeout ⇒ Numeric? Also known as: read_timeout

Returns the receive timeout in seconds, or nil if blocking indefinitely (no timeout). 0 means nonblocking.

Returns:

  • (Numeric, nil) —

    the receive timeout in seconds, or nil if blocking indefinitely (no timeout). 0 means nonblocking.



89
90
91
92
 
# File 'lib/cztop/zsock_options.rb', line 89

def recv_timeout
  value = Zsock.rcvtimeo(self)
  value == -1 ? nil : value / 1000.0
end

#recv_timeout=(timeout) ⇒ Object Also known as: read_timeout=

Parameters:

  • timeout (Numeric, nil) —

    new receive timeout in seconds, or nil to block indefinitely (no timeout). 0 means nonblocking.



98
99
100
 
# File 'lib/cztop/zsock_options.rb', line 98

def recv_timeout=(timeout)
  Zsock.set_rcvtimeo(self, timeout.nil? ? -1 : (timeout * 1000).to_i)
end

#router_mandatory=(bool) ⇒ Object

ZMQ_ROUTER_MANDATORY: Accept only routable messages on ROUTER sockets. Default is off.

Parameters:

  • bool (Boolean) —

    whether to raise a SocketError if a message isn't routable (either if the that peer isn't connected or its SNDHWM is reached)

See Also:



132
133
134
135
 
# File 'lib/cztop/zsock_options.rb', line 132

def router_mandatory=(bool)
  Zsock.set_router_mandatory(self, bool ? 1 : 0)
  @router_mandatory = bool # NOTE: no way to read this option, so we need to remember
end

#router_mandatory? ⇒ Boolean

Returns whether ZMQ_ROUTER_MANDATORY has been set.

Returns:

  • (Boolean) —

    whether ZMQ_ROUTER_MANDATORY has been set



140
141
142
 
# File 'lib/cztop/zsock_options.rb', line 140

def router_mandatory?
  !!@router_mandatory
end

#send_timeout ⇒ Numeric? Also known as: write_timeout

Returns the send timeout in seconds, or nil if blocking indefinitely (no timeout). 0 means nonblocking.

Returns:

  • (Numeric, nil) —

    the send timeout in seconds, or nil if blocking indefinitely (no timeout). 0 means nonblocking.



109
110
111
112
 
# File 'lib/cztop/zsock_options.rb', line 109

def send_timeout
  value = Zsock.sndtimeo(self)
  value == -1 ? nil : value / 1000.0
end

#send_timeout=(timeout) ⇒ Object Also known as: write_timeout=

Parameters:

  • timeout (Numeric, nil) —

    new send timeout in seconds, or nil to block indefinitely (no timeout). 0 means nonblocking.



118
119
120
 
# File 'lib/cztop/zsock_options.rb', line 118

def send_timeout=(timeout)
  Zsock.set_sndtimeo(self, timeout.nil? ? -1 : (timeout * 1000).to_i)
end

#sndhwm ⇒ Integer

Returns the send high water mark.

Returns:

  • (Integer) —

    the send high water mark



57
58
59
 
# File 'lib/cztop/zsock_options.rb', line 57

def sndhwm
  Zsock.sndhwm(self)
end

#sndhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new send high water mark.



64
65
66
 
# File 'lib/cztop/zsock_options.rb', line 64

def sndhwm=(value)
  Zsock.set_sndhwm(self, value)
end

#tcp_keepalive ⇒ Boolean?

Returns TCP keepalive override: true = enabled, false = disabled, nil = OS default (-1).

Returns:

  • (Boolean, nil) —

    TCP keepalive override: true = enabled, false = disabled, nil = OS default (-1)



386
387
388
389
390
391
392
393
 
# File 'lib/cztop/zsock_options.rb', line 386

def tcp_keepalive
  value = Zsock.tcp_keepalive(self)
  case value
  when -1 then nil
  when 0  then false
  when 1  then true
  end
end

#tcp_keepalive=(value) ⇒ Object

Overrides the OS default for TCP keepalive on this socket.

Parameters:

  • value (Boolean, nil) —

    true = enable, false = disable, nil = use OS default



401
402
403
404
405
406
407
408
 
# File 'lib/cztop/zsock_options.rb', line 401

def tcp_keepalive=(value)
  int = case value
        when nil   then -1
        when false then 0
        when true  then 1
        end
  Zsock.set_tcp_keepalive(self, int)
end

#tcp_keepalive_cnt ⇒ Integer?

Returns number of keepalive probes before declaring the connection dead, or nil for OS default.

Returns:

  • (Integer, nil) —

    number of keepalive probes before declaring the connection dead, or nil for OS default



431
432
433
434
 
# File 'lib/cztop/zsock_options.rb', line 431

def tcp_keepalive_cnt
  value = Zsock.tcp_keepalive_cnt(self)
  value == -1 ? nil : value
end

#tcp_keepalive_cnt=(value) ⇒ Object

Parameters:

  • value (Integer, nil) —

    probe count, or nil for OS default



439
440
441
 
# File 'lib/cztop/zsock_options.rb', line 439

def tcp_keepalive_cnt=(value)
  Zsock.set_tcp_keepalive_cnt(self, value.nil? ? -1 : value)
end

#tcp_keepalive_idle ⇒ Integer?

Returns TCP keepalive idle time in seconds, or nil for OS default.

Returns:

  • (Integer, nil) —

    TCP keepalive idle time in seconds, or nil for OS default



414
415
416
417
 
# File 'lib/cztop/zsock_options.rb', line 414

def tcp_keepalive_idle
  value = Zsock.tcp_keepalive_idle(self)
  value == -1 ? nil : value
end

#tcp_keepalive_idle=(value) ⇒ Object

Parameters:

  • value (Integer, nil) —

    idle time in seconds before first keepalive probe, or nil for OS default



423
424
425
 
# File 'lib/cztop/zsock_options.rb', line 423

def tcp_keepalive_idle=(value)
  Zsock.set_tcp_keepalive_idle(self, value.nil? ? -1 : value)
end

#tcp_keepalive_intvl ⇒ Integer?

Returns interval in seconds between keepalive probes, or nil for OS default.

Returns:

  • (Integer, nil) —

    interval in seconds between keepalive probes, or nil for OS default



447
448
449
450
 
# File 'lib/cztop/zsock_options.rb', line 447

def tcp_keepalive_intvl
  value = Zsock.tcp_keepalive_intvl(self)
  value == -1 ? nil : value
end

#tcp_keepalive_intvl=(value) ⇒ Object

Parameters:

  • value (Integer, nil) —

    probe interval in seconds, or nil for OS default



456
457
458
 
# File 'lib/cztop/zsock_options.rb', line 456

def tcp_keepalive_intvl=(value)
  Zsock.set_tcp_keepalive_intvl(self, value.nil? ? -1 : value)
end

#to_io ⇒ IO

Returns IO for FD.

Returns:

  • (IO) —

    IO for FD



48
49
50
 
# File 'lib/cztop/zsock_options.rb', line 48

def to_io
  IO.for_fd fd, autoclose: false
end

#tos ⇒ Integer

Returns current value of Type of Service.

Returns:

  • (Integer) —

    current value of Type of Service



166
167
168
 
# File 'lib/cztop/zsock_options.rb', line 166

def tos
  Zsock.tos(self)
end

#tos=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Type of Service

Raises:

  • (ArgumentError) 


173
174
175
176
177
 
# File 'lib/cztop/zsock_options.rb', line 173

def tos=(new_value)
  raise ArgumentError, 'invalid TOS' unless new_value >= 0

  Zsock.set_tos(self, new_value)
end

#writable? ⇒ Boolean

Checks whether at least one message can be written to the socket without blocking.

Returns:

  • (Boolean) —

    whether the socket is writable



33
34
35
 
# File 'lib/cztop/zsock_options.rb', line 33

def writable?
  (events & POLLOUT).positive?
end