Module: Concurrent::SettableStruct — Concurrent Ruby

# 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`.

See Also:

- Ruby standard library `Struct`
- Java `final` keyword

## Instance Method Summary collapse

- #==(other) ⇒ Boolean

  Equality.

- #[](member) ⇒ Object

  Attribute Reference.

- #[]=(member, value) ⇒ Object

  Attribute Assignment.

- #each {|value| ... } ⇒ undocumented

  Yields the value of each struct member in order.

- #each_pair {|member, value| ... } ⇒ undocumented

  Yields the name and value of each struct member in order.

- #inspect ⇒ String (also: #to_s)

  Describe the contents of this struct in a string.

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

  Returns a new struct containing the contents of `other` and the contents of `self`.

- #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`).

- #to_h ⇒ Hash

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

- #values ⇒ Array (also: #to_a)

  Returns the values for this struct as an Array.

- #values_at(*indexes) ⇒ undocumented

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

## 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| ... } ⇒ `undocumented`

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| ... } ⇒ `undocumented`

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

### #inspect ⇒ `String` 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_h ⇒ `Hash`

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

### #values ⇒ `Array` 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) ⇒ `undocumented`

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