Module: Concurrent::SettableStruct

Defined in:
lib/concurrent-ruby/concurrent/settable_struct.rb

Overview

An thread-safe, write-once variation of Ruby’s standard ‘Struct`. Each member can have its value set at most once, either at construction or any time thereafter. Attempting to assign a value to a member that has already been set will result in a `Concurrent::ImmutabilityError`.

Instance Method Summary collapse

Instance Method Details

#==(other) ⇒ Boolean

Equality

Returns:

  • (Boolean)

    true if other has the same struct subclass and has equal member values (according to ‘Object#==`)



50
51
52
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 50

def ==(other)
  synchronize { ns_equality(other) }
end

#[](member) ⇒ Object

Attribute Reference

Parameters:

  • member (Symbol, String, Integer)

    the string or symbol name of the member for which to obtain the value or the member’s index

Returns:

  • (Object)

    the value of the given struct member or the member at the given index.

Raises:

  • (NameError)

    if the member does not exist

  • (IndexError)

    if the index is out of range.



45
46
47
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 45

def [](member)
  synchronize { ns_get(member) }
end

#[]=(member, value) ⇒ Object

Attribute Assignment

Sets the value of the given struct member or the member at the given index.

Parameters:

  • member (Symbol, String, Integer)

    the string or symbol name of the member for which to obtain the value or the member’s index

Returns:

  • (Object)

    the value of the given struct member or the member at the given index.

Raises:

  • (NameError)

    if the name does not exist

  • (IndexError)

    if the index is out of range.

  • (Concurrent::ImmutabilityError)

    if the given member has already been set



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 75

def []=(member, value)
  if member.is_a? Integer
    length = synchronize { @values.length }
    if member >= length
      raise IndexError.new("offset #{member} too large for struct(size:#{length})")
    end
    synchronize do
      unless @values[member].nil?
        raise Concurrent::ImmutabilityError.new('struct member has already been set')
      end
      @values[member] = value
    end
  else
    send("#{member}=", value)
  end
rescue NoMethodError
  raise NameError.new("no member '#{member}' in struct")
end

#each {|value| ... } ⇒ Object

Yields the value of each struct member in order. If no block is given an enumerator is returned.

Yields:

  • the operation to be performed on each struct member

Yield Parameters:

  • value (Object)

    each struct value (in order)



55
56
57
58
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 55

def each(&block)
  return enum_for(:each) unless block_given?
  synchronize { ns_each(&block) }
end

#each_pair {|member, value| ... } ⇒ Object

Yields the name and value of each struct member in order. If no block is given an enumerator is returned.

Yields:

  • the operation to be performed on each struct member/value pair

Yield Parameters:

  • member (Object)

    each struct member (in order)

  • value (Object)

    each struct value (in order)



61
62
63
64
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 61

def each_pair(&block)
  return enum_for(:each_pair) unless block_given?
  synchronize { ns_each_pair(&block) }
end

#inspectString Also known as: to_s

Describe the contents of this struct in a string.

Returns:

  • (String)

    the contents of this struct in a string



29
30
31
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 29

def inspect
  synchronize { ns_inspect }
end

#merge(other) {|member, selfvalue, othervalue| ... } ⇒ Synchronization::AbstractStruct

Returns a new struct containing the contents of ‘other` and the contents of `self`. If no block is specified, the value for entries with duplicate keys will be that of `other`. Otherwise the value for each duplicate key is determined by calling the block with the key, its value in `self` and its value in `other`.

Parameters:

  • other (Hash)

    the hash from which to set the new values

Yields:

  • an options block for resolving duplicate keys

Yield Parameters:

  • member (String, Symbol)

    the name of the member which is duplicated

  • selfvalue (Object)

    the value of the member in ‘self`

  • othervalue (Object)

    the value of the member in ‘other`

Returns:

  • (Synchronization::AbstractStruct)

    a new struct with the new values

Raises:

  • (ArgumentError)

    of given a member that is not defined in the struct



35
36
37
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 35

def merge(other, &block)
  synchronize { ns_merge(other, &block) }
end

#select {|value| ... } ⇒ Array

Yields each member value from the struct to the block and returns an Array containing the member values from the struct for which the given block returns a true value (equivalent to ‘Enumerable#select`).

Yields:

  • the operation to be performed on each struct member

Yield Parameters:

  • value (Object)

    each struct value (in order)

Returns:

  • (Array)

    an array containing each value for which the block returns true



67
68
69
70
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 67

def select(&block)
  return enum_for(:select) unless block_given?
  synchronize { ns_select(&block) }
end

#to_hHash

Returns a hash containing the names and values for the struct’s members.

Returns:

  • (Hash)

    the names and values for the struct’s members



40
41
42
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 40

def to_h
  synchronize { ns_to_h }
end

#valuesArray Also known as: to_a

Returns the values for this struct as an Array.

Returns:

  • (Array)

    the values for this struct



18
19
20
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 18

def values
  synchronize { ns_values }
end

#values_at(*indexes) ⇒ Object

Returns the struct member values for each selector as an Array.

A selector may be either an Integer offset or a Range of offsets (as in ‘Array#values_at`).

Parameters:

  • indexes (Fixnum, Range)

    the index(es) from which to obatin the values (in order)



24
25
26
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 24

def values_at(*indexes)
  synchronize { ns_values_at(indexes) }
end