Class: Prosody::DequeState

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

Overview

A deque keyed-state handle.

Instance Method Summary collapse

Methods included from State::Scanning

#scan_each, #scan_items

Constructor Details

#initialize(native) ⇒ DequeState

Returns a new instance of DequeState.

Parameters:



621
622
623
 
# File 'lib/prosody/state.rb', line 621

def initialize(native)
  @native = native
end

Instance Method Details

#<<(value) ⇒ self

Appends value at the back and returns self for chaining (mirrors Array#<<).

Parameters:

  • value (Object)

Returns:

  • (self) 


743
744
745
746
 
# File 'lib/prosody/state.rb', line 743

def <<(value)
  push(value)
  self
end

#append(value) ⇒ self

Appends value, returning self for chaining (mirrors Array#append). A wrapper, not an alias: the native write returns nil.

Parameters:

  • value (Object)

Returns:

  • (self) 


733
734
735
736
 
# File 'lib/prosody/state.rb', line 733

def append(value)
  push(value)
  self
end

#at_negative(index) ⇒ T?

Resolves a negative Array-style index against the current length: -1 fast-paths through #last (no length read), other negatives read the length and index from the front. Returns nil when the index resolves before the front (past the far end of the deque).

Parameters:

  • index (Integer)

Returns:

  • (T, nil) 


798
799
800
801
802
803
 
# File 'lib/prosody/state.rb', line 798

def at_negative(index)
  return @native.peek_back if index == -1

  resolved = @native.len + index
  resolved.negative? ? nil : @native.get(resolved)
end

#clear ⇒ void

This method returns an undefined value.

Removes every element.



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

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



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

def commit = @native.commit

#each ⇒ void #each ⇒ Enumerator[T, void]

Traverses the live elements in index order.

Without a block, returns an Enumerator over the native scan. Each step fiber-yields; the scan is closed via ensure on stop or exception.

Overloads:

  • #each ⇒ void

    This method returns an undefined value.

  • #each ⇒ Enumerator[T, void]

    Returns:

    • (Enumerator[T, void])

Yields:

Yield Parameters:

  • element (Object)
  • arg0 (T)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


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

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

#empty? ⇒ Boolean

Whether the deque holds no live elements.

Returns:

  • (Boolean) 


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

def empty? = @native.is_empty

#fetch(index) ⇒ T #fetch ⇒ void #fetch ⇒ void

Reads the element at index, raising or defaulting when out of range (mirrors Array#fetch). A nil result is unambiguously "out of range" under the null ban. Negatives resolve Array-style like #get — -1 is the back element, -n the nth from the end; a fractional or non-Integer index is a caller mistake, rejected TransientStateError.

Overloads:

  • #fetch(index) ⇒ T

    Parameters:

    • index (Integer)

    Returns:

    • (T)
  • #fetch ⇒ void

    This method returns an undefined value.

  • #fetch ⇒ void

    This method returns an undefined value.

Parameters:

  • index (Integer) —

    the position (negative counts from the back)

  • default (Object) —

    returned when index is out of range

Yield Parameters:

  • index (Integer) —

    called (instead of default) when out of range

Returns:

  • (Object)

Raises:

  • (IndexError) —

    when out of range and no default or block is given

  • (TransientStateError) —

    if index is not an Integer



775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
 
# File 'lib/prosody/state.rb', line 775

def fetch(index, *default, &block)
  if default.length > 1
    raise ArgumentError, "wrong number of arguments (given #{default.length + 1}, expected 1..2)"
  end
  unless index.is_a?(Integer)
    raise TransientStateError, "fetch: index must be an Integer, got #{index.inspect}"
  end
  warn "warning: block supersedes default value argument" if block && !default.empty?

  value = index.negative? ? at_negative(index) : @native.get(index)
  return value unless value.nil?
  return block.call(index) if block
  return default.first unless default.empty?

  raise IndexError, "index #{index} outside deque bounds"
end

#first ⇒ Object?

The front element, or nil when empty (mirrors Array#first). An endpoint-slot read in one round trip (no length read). Under a TTL an expired front slot yields nil even when live interior elements remain — a peek never searches inward.

Returns:

  • (Object, nil) 


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

def first = @native.peek_front

#get(index) ⇒ Object?

Reads the element at index, resolving negatives Array-style (mirrors +Array#[]+'s read domain, without the indexer). A non-negative index reads from the front; -1 is the back element, -n the nth from the end. -1 fast-paths through #last (no length read); other negatives resolve against the current length (one length read + one element read), consistent because the deque has a single writer per attempt.

Parameters:

  • index (Integer) —

    the position (negative counts from the back)

Returns:

  • (Object, nil) —

    the element, or nil outside the bounds

Raises:



686
687
688
689
690
691
 
# File 'lib/prosody/state.rb', line 686

def get(index)
  unless index.is_a?(Integer)
    raise TransientStateError, "get: index must be an Integer, got #{index.inspect}"
  end
  index.negative? ? at_negative(index) : @native.get(index)
end

#last ⇒ Object?

The back element, or nil when empty (mirrors Array#last). An endpoint-slot read in one round trip (no length read); same TTL-hole semantics as #first.

Returns:

  • (Object, nil) 


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

def last = @native.peek_back

#length ⇒ Integer Also known as: size

The number of live elements.

Returns:

  • (Integer) 


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

def length = @native.len

#pop ⇒ Object?

Removes and returns the back element.

Returns:

  • (Object, nil) —

    the removed element, or nil when empty



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

def pop = @native.pop_back

#prepend(value) ⇒ self

idiomatic Array-style conveniences (bounded reads only). #get and #fetch take a single Integer index (negatives resolve from the back, Array-style); #[] and #at are deliberately absent because they would invite a range read the remote deque cannot honor.

Parameters:

  • value (T)

Returns:

  • (self) 


723
724
725
726
 
# File 'lib/prosody/state.rb', line 723

def prepend(value)
  unshift(value)
  self
end

#push(value) ⇒ void

This method returns an undefined value.

Appends an element at the back.

Parameters:

  • value (Object) —

    the element (JSON, or a message)

Raises:



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

def push(value) = @native.push_back(value)

#reverse_each ⇒ void #reverse_each ⇒ Enumerator[T, void]

Traverses the live elements in reverse index order.

Overloads:

  • #reverse_each ⇒ void

    This method returns an undefined value.

  • #reverse_each ⇒ Enumerator[T, void]

    Returns:

    • (Enumerator[T, void])

Yields:

Yield Parameters:

  • element (Object)
  • arg0 (T)

Yield Returns:

  • (void)

Returns:

  • (Enumerator, void) 


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

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

#rollback ⇒ nil

Discards the buffered uncommitted operations.

Returns:

  • (nil) 


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

def rollback = @native.rollback

#shift ⇒ Object?

Removes and returns the front element.

Returns:

  • (Object, nil) —

    the removed element, or nil when empty



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

def shift = @native.pop_front

#traverse(direction) ⇒ void #traverse(direction) ⇒ Enumerator[T, void]

Overloads:

  • #traverse(direction) ⇒ void

    This method returns an undefined value.

    Parameters:

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

    Parameters:

    • direction (Symbol)

    Returns:

    • (Enumerator[T, void])

Yields:

Yield Parameters:

  • arg0 (T)

Yield Returns:

  • (void) 


805
806
807
808
809
 
# File 'lib/prosody/state.rb', line 805

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

  scan_each(direction) { |item| yield item }
end

#unshift(value) ⇒ void

This method returns an undefined value.

Prepends an element at the front.

Parameters:

  • value (Object) —

    the element (JSON, or a message)

Raises:



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

def unshift(value) = @native.push_front(value)