Class: Prosody::MapState

Inherits:
Object
  • Object
show all
Includes:
State::Scanning
Defined in:
lib/prosody/state.rb,
sig/state.rbs

Overview

A String-keyed ordered-map keyed-state handle.

Instance Method Summary collapse

Methods included from State::Scanning

#scan_each, #scan_items

Constructor Details

#initialize(native) ⇒ MapState

Returns a new instance of MapState.

Parameters:



380
381
382
 
# File 'lib/prosody/state.rb', line 380

def initialize(native)
  @native = native
end

Instance Method Details

#clear ⇒ void

This method returns an undefined value.

Removes every entry.



419
 
# File 'lib/prosody/state.rb', line 419

def clear = @native.clear

#commit ⇒ nil

Durably commits the buffered operations mid-handler.

Returns:

  • (nil) —

    the erased FFI seam drops the applied/no-op outcome



424
 
# File 'lib/prosody/state.rb', line 424

def commit = @native.commit

#delete(key) ⇒ nil

Removes key.

Documented divergence from Hash#delete: this returns nil, never the removed value (the erased FFI seam does not surface it).

Parameters:

  • key (String) —

    the map key

Returns:

  • (nil) 


411
412
413
414
 
# File 'lib/prosody/state.rb', line 411

def delete(key)
  @native.remove(key)
  nil
end

#dig(key, *rest) ⇒ Object?

Reads key and digs into the nested value (mirrors Hash#dig). A single bounded read; digging continues in the returned local value.

Parameters:

  • key (String)
  • (Object)

Returns:

  • (Object, nil)

Raises:

  • (TypeError) —

    if a nested value does not respond to dig



546
547
548
549
550
551
552
553
554
555
 
# File 'lib/prosody/state.rb', line 546

def dig(key, *rest)
  value = @native.get(key)
  return value if rest.empty? || value.nil?

  unless value.respond_to?(:dig)
    raise TypeError, "#{value.class} does not have #dig method"
  end

  value.dig(*rest)
end

#each_key ⇒ void #each_key ⇒ Enumerator[String, void]

Traverses the live keys in key order, yielding each key (mirrors Hash#each_key). The key scan skips value decode and the resolver — a message-backed map yields keys with zero Kafka fetches, though not zero-I/O. Without a block, returns a demand-driven Enumerator; there is deliberately no eager keys array (it would materialize the whole remote keyset). Mirrors #each_pair's block-form return (+nil+), not stdlib's self, for in-repo sibling consistency.

Overloads:

  • #each_key ⇒ void

    This method returns an undefined value.

  • #each_key ⇒ Enumerator[String, void]

    Returns:

    • (Enumerator[String, void])

Yields:

Yield Parameters:

  • key (String)
  • arg0 (String)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


459
 
# File 'lib/prosody/state.rb', line 459

def each_key(&block) = traverse_keys(:forward, &block)

#each_pair ⇒ void #each_pair ⇒ Enumerator[[ String, V ], void] Also known as: each

Traverses the live entries in key order, yielding key, value.

Without a block, returns an Enumerator over the native scan. Each step fiber-yields; the scan is closed via ensure on stop or exception. The enumerator is valid only within the current handler invocation.

Overloads:

  • #each_pair ⇒ void

    This method returns an undefined value.

  • #each_pair ⇒ Enumerator[[ String, V ], void]

    Returns:

    • (Enumerator[[ String, V ], void])

Yields:

Yield Parameters:

  • key (String)
  • value (Object)
  • arg0 (String)
  • arg1 (V)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


440
 
# File 'lib/prosody/state.rb', line 440

def each_pair(&block) = traverse(:forward, &block)

#each_value ⇒ void #each_value ⇒ Enumerator[V, void]

Overloads:

  • #each_value ⇒ void

    This method returns an undefined value.

  • #each_value ⇒ Enumerator[V, void]

    Returns:

    • (Enumerator[V, void])

Yields:

Yield Parameters:

  • arg0 (V)

Yield Returns:

  • (void) 


466
 
# File 'lib/prosody/state.rb', line 466

def each_value(&block) = traverse_values(:forward, &block)

#fetch(key) ⇒ V #fetch ⇒ void #fetch ⇒ void

Reads key, raising or defaulting when absent (mirrors Hash#fetch). Performs a single read; a nil result is unambiguously "absent" under the null ban.

Overloads:

  • #fetch(key) ⇒ V

    Parameters:

    • key (String)

    Returns:

    • (V)
  • #fetch ⇒ void

    This method returns an undefined value.

  • #fetch ⇒ void

    This method returns an undefined value.

Parameters:

  • key (String)
  • default (Object) —

    returned when key is absent

Yield Parameters:

  • key (String) —

    called (instead of default) when key is absent

Returns:

  • (Object)

Raises:

  • (KeyError) —

    when key is absent and no default or block is given



513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/prosody/state.rb', line 513

def fetch(key, *default, &block)
  if default.length > 1
    raise ArgumentError, "wrong number of arguments (given #{default.length + 1}, expected 1..2)"
  end
  warn "warning: block supersedes default value argument" if block && !default.empty?

  value = @native.get(key)
  return value unless value.nil?
  return block.call(key) if block
  return default.first unless default.empty?

  raise KeyError.new("key not found: #{key.inspect}", key: key, receiver: self)
end

#fetch_values(keys) ⇒ Array[V] #fetch_values ⇒ void

Reads keys as a single bounded batch, requiring every key to be present (mirrors Hash#fetch_values). Without a block, a missing key raises KeyError; with a block, the block is called with each missing key and its result substituted.

Overloads:

  • #fetch_values(keys) ⇒ Array[V]

    Parameters:

    • keys (String)

    Returns:

    • (Array[V])
  • #fetch_values ⇒ void

    This method returns an undefined value.

Parameters:

  • keys (Array<String>) —

    the keys to read, in order

Yield Parameters:

  • key (String) —

    called for each absent key

Returns:

  • (Array<Object>) —

    one value per key, in order

Raises:

  • (KeyError) —

    when a key is absent and no block is given



579
580
581
582
583
584
585
586
 
# File 'lib/prosody/state.rb', line 579

def fetch_values(*keys, &block)
  keys.zip(get_many(keys)).map do |key, value|
    next value unless value.nil?
    next block.call(key) if block

    raise KeyError.new("key not found: #{key.inspect}", key: key, receiver: self)
  end
end

#get(key) ⇒ Object? Also known as: []

Reads the value for key.

Parameters:

  • key (String) —

    the map key

Returns:

  • (Object, nil) —

    the value, or nil when the key is absent



388
 
# File 'lib/prosody/state.rb', line 388

def get(key) = @native.get(key)

#get_many(keys) ⇒ Array<Object, nil>

Reads several keys in a single isolated batch.

Parameters:

  • keys (Array<String>) —

    the keys to read, in order

Returns:

  • (Array<Object, nil>) —

    one result per input key; nil for absent keys



394
 
# File 'lib/prosody/state.rb', line 394

def get_many(keys) = @native.get_many(keys)

#key?(key) ⇒ Boolean Also known as: has_key?, include?, member?

Whether key has a live value (mirrors Hash#key?). A presence check: no value decode and no resolver run (not no-I/O). A message-backed map answers presence with zero Kafka fetches — true even for a present-but-unfetchable cell — though a cache miss may still touch the store.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


535
 
# File 'lib/prosody/state.rb', line 535

def key?(key) = @native.contains_key(key)

#reverse_each_key ⇒ void #reverse_each_key ⇒ Enumerator[String, void]

Traverses the live keys in reverse key order, yielding each key.

Overloads:

  • #reverse_each_key ⇒ void

    This method returns an undefined value.

  • #reverse_each_key ⇒ Enumerator[String, void]

    Returns:

    • (Enumerator[String, void])

Yields:

Yield Parameters:

  • key (String)
  • arg0 (String)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


465
 
# File 'lib/prosody/state.rb', line 465

def reverse_each_key(&block) = traverse_keys(:backward, &block)

#reverse_each_pair ⇒ void #reverse_each_pair ⇒ Enumerator[[ String, V ], void]

Traverses the live entries in reverse key order, yielding key, value.

Overloads:

  • #reverse_each_pair ⇒ void

    This method returns an undefined value.

  • #reverse_each_pair ⇒ Enumerator[[ String, V ], void]

    Returns:

    • (Enumerator[[ String, V ], void])

Yields:

Yield Parameters:

  • key (String)
  • value (Object)
  • arg0 (String)
  • arg1 (V)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


447
 
# File 'lib/prosody/state.rb', line 447

def reverse_each_pair(&block) = traverse(:backward, &block)

#reverse_each_value ⇒ void #reverse_each_value ⇒ Enumerator[V, void]

Overloads:

  • #reverse_each_value ⇒ void

    This method returns an undefined value.

  • #reverse_each_value ⇒ Enumerator[V, void]

    Returns:

    • (Enumerator[V, void])

Yields:

Yield Parameters:

  • arg0 (V)

Yield Returns:

  • (void) 


467
 
# File 'lib/prosody/state.rb', line 467

def reverse_each_value(&block) = traverse_values(:backward, &block)

#rollback ⇒ nil

Discards the buffered uncommitted operations.

Returns:

  • (nil) 


429
 
# File 'lib/prosody/state.rb', line 429

def rollback = @native.rollback

#set(key, value) ⇒ void Also known as: []=

This method returns an undefined value.

Inserts or overwrites key.

Parameters:

  • key (String) —

    the map key

  • value (Object) —

    the value to store (JSON, or a message)

Raises:



402
 
# File 'lib/prosody/state.rb', line 402

def set(key, value) = @native.set(key, value)

#slice(*keys) ⇒ Hash{String => Object}

Reads keys as a single bounded batch, returning a Hash of only the keys that are present (mirrors Hash#slice). Absent keys are omitted.

Parameters:

  • keys (Array<String>) —

    the keys to read

Returns:

  • (Hash{String => Object}) —

    present keys mapped to their values



562
563
564
565
566
567
568
 
# File 'lib/prosody/state.rb', line 562

def slice(*keys)
  result = {}
  keys.zip(get_many(keys)) do |key, value|
    result[key] = value unless value.nil?
  end
  result
end

#store(key, value) ⇒ Object

Writes key, returning the stored value (mirrors Hash#store). A wrapper, not an alias: unlike []=, store is called normally, so its return is observed — and the native write returns nil.

Parameters:

  • key (String)
  • value (Object)

Returns:

  • (Object) —

    the stored value



489
490
491
492
 
# File 'lib/prosody/state.rb', line 489

def store(key, value)
  set(key, value)
  value
end

#traverse(direction) ⇒ void #traverse(direction) ⇒ Enumerator[[ String, V ], void]

Overloads:

  • #traverse(direction) ⇒ void

    This method returns an undefined value.

    Parameters:

    • direction (Symbol)
  • #traverse(direction) ⇒ Enumerator[[ String, V ], void]

    Parameters:

    • direction (Symbol)

    Returns:

    • (Enumerator[[ String, V ], void])

Yields:

Yield Parameters:

  • arg0 (String)
  • arg1 (V)

Yield Returns:

  • (void) 


590
591
592
593
594
595
596
597
 
# File 'lib/prosody/state.rb', line 590

def traverse(direction)
  return enum_for(:traverse, direction) unless block_given?

  # Yield the [key, value] pair as a single Array, matching Hash#each_pair:
  # a two-parameter block auto-splats it (|k, v|), a one-parameter block
  # receives the pair (|pair|), and the no-block Enumerator yields pairs.
  scan_each(direction) { |pair| yield pair }
end

#traverse_keys(direction) ⇒ void #traverse_keys(direction) ⇒ Enumerator[String, void]

Overloads:

  • #traverse_keys(direction) ⇒ void

    This method returns an undefined value.

    Parameters:

    • direction (Symbol)
  • #traverse_keys(direction) ⇒ Enumerator[String, void]

    Parameters:

    • direction (Symbol)

    Returns:

    • (Enumerator[String, void])

Yields:

Yield Parameters:

  • arg0 (String)

Yield Returns:

  • (void) 


599
600
601
602
603
 
# File 'lib/prosody/state.rb', line 599

def traverse_keys(direction)
  return enum_for(:traverse_keys, direction) unless block_given?

  scan_each(direction, :keys) { |key| yield key }
end

#values_at(*keys) ⇒ Array<Object, nil>

Reads several keys positionally (mirrors Hash#values_at).

Parameters:

  • keys (Array<String>) —

    the keys to read

Returns:

  • (Array<Object, nil>) —

    one result per key; nil for absent keys



502
 
# File 'lib/prosody/state.rb', line 502

def values_at(*keys) = get_many(keys)