Class: CZTop::ZsockOptions::OptionsAccessor

Inherits:
Object
  • Object
show all
Includes:
CZMQ::FFI
Defined in:
lib/cztop/zsock_options.rb

Overview

Used to access the options of a Socket or Actor.

Security Mechanisms collapse

MECHANISMS =

supported security mechanisms and their macro value equivalent

{
  0 => :NULL,  # ZMQ_NULL
  1 => :PLAIN, # ZMQ_PLAIN
  2 => :CURVE, # ZMQ_CURVE
  3 => :GSSAPI # ZMQ_GSSAPI
}

Instance Attribute Summary collapse

High Water Marks collapse

Security Mechanisms collapse

Send and Receive Timeouts collapse

Instance Method Summary collapse

Constructor Details

#initialize(zocket) ⇒ OptionsAccessor

Returns a new instance of OptionsAccessor.

Parameters:



46
47
48
 
# File 'lib/cztop/zsock_options.rb', line 46

def initialize(zocket)
  @zocket = zocket
end

Instance Attribute Details

#zocket ⇒ Socket, Actor (readonly)

Returns whose options this CZTop::ZsockOptions::OptionsAccessor instance is accessing.

Returns:



43
44
45
 
# File 'lib/cztop/zsock_options.rb', line 43

def zocket
  @zocket
end

Instance Method Details

#[](option_name) ⇒ Object

Fuzzy option getter. This is to make it easier when porting applications from CZMQ libraries to CZTop.

Parameters:

  • option_name (Symbol, String) —

    case insensitive option name

Raises:

  • (NoMethodError) —

    if option name can’t be recognized



54
55
56
57
58
59
60
 
# File 'lib/cztop/zsock_options.rb', line 54

def [](option_name)
  # NOTE: beware of predicates, especially #CURVE_server? & friends
  meth = public_methods.reject { |m| m =~ /=$/ }
        .find { |m| m =~ /^#{option_name}\??$/i }
  raise NoMethodError, option_name if meth.nil?
  __send__(meth)
end

#[]=(option_name, new_value) ⇒ Object

Fuzzy option setter. This is to make it easier when porting applications from CZMQ libraries to CZTop.

Parameters:

  • option_name (Symbol, String) —

    case insensitive option name

  • new_value (String, Integer) —

    new value

Raises:

  • (NoMethodError) —

    if option name can’t be recognized



67
68
69
70
71
 
# File 'lib/cztop/zsock_options.rb', line 67

def []=(option_name, new_value)
  meth = public_methods.find { |m| m =~ /^#{option_name}=$/i }
  raise NoMethodError, option_name if meth.nil?
  __send__(meth, new_value)
end

#CURVE_key(key_name) ⇒ String? (private)

Get one of the CURVE keys.

Parameters:

  • key_name (Symbol) —

    something like :curve_serverkey

Returns:

  • (String, nil) —

    key, if CURVE is supported and active, or nil



110
111
112
113
114
115
 
# File 'lib/cztop/zsock_options.rb', line 110

def CURVE_key(key_name)
  return nil if mechanism != :CURVE
  ptr = Zsock.__send__(key_name, @zocket)
  return nil if ptr.null?
  ptr.read_string
end

#CURVE_publickey ⇒ String?

Returns:

  • (String) —

    Z85 encoded public key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



162
163
164
 
# File 'lib/cztop/zsock_options.rb', line 162

def CURVE_publickey
  CURVE_key(:curve_publickey)
end

#CURVE_secretkey ⇒ String?

Returns:

  • (String) —

    Z85 encoded secret key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



155
156
157
 
# File 'lib/cztop/zsock_options.rb', line 155

def CURVE_secretkey
  CURVE_key(:curve_secretkey)
end

#CURVE_server=(bool) ⇒ Object

Note:

You’ll have to use a Authenticator.

Make this zocket a CURVE server.

Parameters:

  • bool (Boolean) 


96
97
98
 
# File 'lib/cztop/zsock_options.rb', line 96

def CURVE_server=(bool)
  Zsock.set_curve_server(@zocket, bool ? 1 : 0)
end

#CURVE_server? ⇒ Boolean

Returns whether this zocket is a CURVE server.

Returns:

  • (Boolean) —

    whether this zocket is a CURVE server



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

def CURVE_server?() Zsock.curve_server(@zocket) > 0 end

#CURVE_serverkey ⇒ String?

Returns:

  • (String) —

    Z85 encoded server key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



103
104
105
 
# File 'lib/cztop/zsock_options.rb', line 103

def CURVE_serverkey
  CURVE_key(:curve_serverkey)
end

#CURVE_serverkey=(key) ⇒ Object

Sets the server’s public key, so the zocket can authenticate the remote server.

Parameters:

  • key (String) —

    Z85 (40 bytes) or binary (32 bytes) server key

Raises:

  • (ArgumentError) —

    if key has wrong size



122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/cztop/zsock_options.rb', line 122

def CURVE_serverkey=(key)
  case key.bytesize
  when 40
    Zsock.set_curve_serverkey(@zocket, key)
  when 32
    ptr = ::FFI::MemoryPointer.from_string(key)
    Zsock.set_curve_serverkey_bin(@zocket, ptr)
  else
    raise ArgumentError, "invalid server key: %p" % key
  end
end

#events ⇒ Integer

Returns socket events (readable/writable).

Returns:

  • (Integer) —

    socket events (readable/writable)

See Also:



320
 
# File 'lib/cztop/zsock_options.rb', line 320

def events() Zsock.events(@zocket) end

#fd ⇒ Integer

Returns socket file descriptor.

Returns:

  • (Integer) —

    socket file descriptor



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

def fd() Zsock.fd(@zocket) end

#heartbeat_ivl ⇒ Integer

Returns current value of Heartbeat IVL.

Returns:

  • (Integer) —

    current value of Heartbeat IVL



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

def heartbeat_ivl() Zsock.heartbeat_ivl(@zocket) end

#heartbeat_ivl=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat IVL

Raises:

  • (ArgumentError) 


260
261
262
263
 
# File 'lib/cztop/zsock_options.rb', line 260

def heartbeat_ivl=(new_value)
  raise ArgumentError, "invalid IVL" unless new_value >= 0
  Zsock.set_heartbeat_ivl(@zocket, new_value)
end

#heartbeat_timeout ⇒ Integer

Returns current value of Heartbeat Timeout.

Returns:

  • (Integer) —

    current value of Heartbeat Timeout



282
 
# File 'lib/cztop/zsock_options.rb', line 282

def heartbeat_timeout() Zsock.heartbeat_timeout(@zocket) end

#heartbeat_timeout=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat Timeout

Raises:

  • (ArgumentError) 


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

def heartbeat_timeout=(new_value)
  raise ArgumentError, "invalid timeout" unless new_value >= 0
  Zsock.set_heartbeat_timeout(@zocket, new_value)
end

#heartbeat_ttl ⇒ Integer

Returns current value of Heartbeat TTL, in milliseconds.

Returns:

  • (Integer) —

    current value of Heartbeat TTL, in milliseconds



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

def heartbeat_ttl() Zsock.heartbeat_ttl(@zocket) end

#heartbeat_ttl=(new_value) ⇒ Object

Note:

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

Parameters:

  • new_value (Integer) —

    new value for Heartbeat TTL, in milliseconds



271
272
273
274
275
276
277
278
279
 
# File 'lib/cztop/zsock_options.rb', line 271

def heartbeat_ttl=(new_value)
  unless new_value.is_a? Integer
    raise ArgumentError, "invalid TTL: #{new_value}"
  end
  unless (0..65536).include? new_value
    raise ArgumentError, "TTL out of range: #{new_value}"
  end
  Zsock.set_heartbeat_ttl(@zocket, new_value)
end

#identity ⇒ String

Returns current socket identity.

Returns:

  • (String) —

    current socket identity



239
 
# File 'lib/cztop/zsock_options.rb', line 239

def identity() Zsock.identity(@zocket).read_string end

#identity=(identity) ⇒ Object

Parameters:

  • identity (String) —

    new socket identity

Raises:

  • (ArgumentError) —

    if identity is invalid



242
243
244
245
246
247
 
# File 'lib/cztop/zsock_options.rb', line 242

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(@zocket, identity)
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



311
312
313
 
# File 'lib/cztop/zsock_options.rb', line 311

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

#ipv6? ⇒ Boolean

Returns current value of ipv6.

Returns:

  • (Boolean) —

    current value of ipv6



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

def ipv6?() Zsock.ipv6(@zocket) != 0 end

#linger ⇒ Integer

Returns current value of LINGER.

Returns:

  • (Integer) —

    current value of LINGER



290
 
# File 'lib/cztop/zsock_options.rb', line 290

def linger() Zsock.linger(@zocket) end

#linger=(new_value) ⇒ Object

This defines the number of milliseconds to wait while closing/disconnecting a socket if there are outstanding messages to send.

Default is 0, which means to not wait at all. -1 means to wait indefinitely

Parameters:

  • new_value (Integer) —

    new value for LINGER



299
300
301
 
# File 'lib/cztop/zsock_options.rb', line 299

def linger=(new_value)
  Zsock.set_linger(@zocket, new_value)
end

#mechanism ⇒ Symbol

Note:

This is automatically set through the use of CURVE certificates, etc

Returns the current security mechanism in use.

Returns:

  • (Symbol) —

    the current security mechanism in use



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

def mechanism
  #int zsock_mechanism (void *self);
  code = Zsock.mechanism(@zocket)
  MECHANISMS[code] or
    raise "unknown ZMQ security mechanism code: %i" % code
end

#PLAIN_password ⇒ String?

Returns:

  • (String) —

    password set for PLAIN mechanism

  • (nil) —

    if the current mechanism isn’t PLAIN



202
203
204
205
 
# File 'lib/cztop/zsock_options.rb', line 202

def PLAIN_password
  return nil if mechanism != :PLAIN
  Zsock.plain_password(@zocket).read_string
end

#PLAIN_password=(password) ⇒ Object

Parameters:

  • password (String) —

    password for PLAIN mechanism



207
208
209
 
# File 'lib/cztop/zsock_options.rb', line 207

def PLAIN_password=(password)
  Zsock.set_plain_password(@zocket, password)
end

#PLAIN_server=(bool) ⇒ Object

Note:

You’ll have to use a Authenticator.

Make this zocket a PLAIN server.

Parameters:

  • bool (Boolean) 


185
186
187
 
# File 'lib/cztop/zsock_options.rb', line 185

def PLAIN_server=(bool)
  Zsock.set_plain_server(@zocket, bool ? 1 : 0)
end

#PLAIN_server? ⇒ Boolean

Returns whether this zocket is a PLAIN server.

Returns:

  • (Boolean) —

    whether this zocket is a PLAIN server



180
 
# File 'lib/cztop/zsock_options.rb', line 180

def PLAIN_server?() Zsock.plain_server(@zocket) > 0 end

#PLAIN_username ⇒ String?

Returns:

  • (String) —

    username set for PLAIN mechanism

  • (nil) —

    if the current mechanism isn’t PLAIN



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

def PLAIN_username
  return nil if mechanism != :PLAIN
  Zsock.plain_username(@zocket).read_string
end

#PLAIN_username=(username) ⇒ Object

Note:

You’ll have to use a Authenticator.

Parameters:

  • username (String) —

    username for PLAIN mechanism



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

def PLAIN_username=(username)
  Zsock.set_plain_username(@zocket, username)
end

#rcvhwm ⇒ Integer

Returns the receive high water mark.

Returns:

  • (Integer) —

    the receive high water mark



82
 
# File 'lib/cztop/zsock_options.rb', line 82

def rcvhwm() Zsock.rcvhwm(@zocket) end

#rcvhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new receive high water mark



84
 
# File 'lib/cztop/zsock_options.rb', line 84

def rcvhwm=(value) Zsock.set_rcvhwm(@zocket, value) end

#rcvtimeo ⇒ Integer

Returns the timeout when receiving a message.

Returns:

  • (Integer) —

    the timeout when receiving a message

See Also:



217
 
# File 'lib/cztop/zsock_options.rb', line 217

def rcvtimeo() Zsock.rcvtimeo(@zocket) end

#rcvtimeo=(timeout) ⇒ Object

Parameters:

  • timeout (Integer) —

    new timeout

See Also:



220
 
# File 'lib/cztop/zsock_options.rb', line 220

def rcvtimeo=(timeout) Zsock.set_rcvtimeo(@zocket, timeout) end

#reconnect_ivl ⇒ Integer

Returns current value of RECONNECT_IVL.

Returns:

  • (Integer) —

    current value of RECONNECT_IVL



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

def reconnect_ivl() Zsock.reconnect_ivl(@zocket) end

#reconnect_ivl=(new_value) ⇒ Object

This defines the number of milliseconds to wait while closing/disconnecting a socket if there are outstanding messages to send.

Default is 0, which means to not wait at all. -1 means to wait indefinitely

Parameters:

  • new_value (Integer) —

    new value for RECONNECT_IVL



332
333
334
 
# File 'lib/cztop/zsock_options.rb', line 332

def reconnect_ivl=(new_value)
  Zsock.set_reconnect_ivl(@zocket, new_value)
end

#router_mandatory=(bool) ⇒ Object

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

Parameters:

  • bool (Boolean) —

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



234
235
236
 
# File 'lib/cztop/zsock_options.rb', line 234

def router_mandatory=(bool)
  Zsock.set_router_mandatory(@zocket, bool ? 1 : 0)
end

#sndhwm ⇒ Integer

Returns the send high water mark.

Returns:

  • (Integer) —

    the send high water mark



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

def sndhwm() Zsock.sndhwm(@zocket) end

#sndhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new send high water mark.



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

def sndhwm=(value) Zsock.set_sndhwm(@zocket, value) end

#sndtimeo ⇒ Integer

Returns the timeout when sending a message.

Returns:

  • (Integer) —

    the timeout when sending a message

See Also:



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

def sndtimeo() Zsock.sndtimeo(@zocket) end

#sndtimeo=(timeout) ⇒ Object

Parameters:

  • timeout (Integer) —

    new timeout

See Also:



227
 
# File 'lib/cztop/zsock_options.rb', line 227

def sndtimeo=(timeout) Zsock.set_sndtimeo(@zocket, timeout) end

#tos ⇒ Integer

Returns current value of Type of Service.

Returns:

  • (Integer) —

    current value of Type of Service



250
 
# File 'lib/cztop/zsock_options.rb', line 250

def tos() Zsock.tos(@zocket) end

#tos=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Type of Service

Raises:

  • (ArgumentError) 


252
253
254
255
 
# File 'lib/cztop/zsock_options.rb', line 252

def tos=(new_value)
  raise ArgumentError, "invalid TOS" unless new_value >= 0
  Zsock.set_tos(@zocket, new_value)
end

#zap_domain ⇒ String

Gets the ZAP domain used for authentication.

Returns:

  • (String)

See Also:



169
170
171
 
# File 'lib/cztop/zsock_options.rb', line 169

def zap_domain
  Zsock.zap_domain(@zocket).read_string
end

#zap_domain=(domain) ⇒ Object

Sets the ZAP domain used for authentication.

Parameters:

  • domain (String) —

    the new ZAP domain

Raises:

  • (ArgumentError) 


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

def zap_domain=(domain)
  raise ArgumentError, "domain too long" if domain.bytesize > 254
  Zsock.set_zap_domain(@zocket, domain)
end