Module: Concurrent::SettableStruct

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `Synchronization::AbstractStruct`
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 ImmutabilityError.

Constant Summary

FACTORY = private
# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 115

Class.new(Synchronization::LockableObject) do
  def define_struct(name, members, &block)
    synchronize do
      clazz = Synchronization::AbstractStruct.define_struct_class(SettableStruct, Synchronization::LockableObject, name, members, &block)
      members.each_with_index do |member, index|
        clazz.send :remove_method, member if clazz.instance_methods.include? member
        clazz.send(:define_method, member) do
          synchronize { @values[index] }
        end
        clazz.send(:define_method, "#{member}=") do |value|
          synchronize do
            unless @values[index].nil?
              raise Concurrent::ImmutabilityError.new('struct member has already been set')
            end
            @values[index] = value
          end
        end
      end
      clazz
    end
  end
end.new

Class Method Summary

.new(*args, &block) private

Factory for creating new struct classes.

Instance Method Summary

#==(other) ⇒ Boolean

Equality.
#[](member) ⇒ Object

Attribute Reference.
#[]=(member, value) ⇒ Object

Attribute Assignment.
#each {|value| ... }

Yields the value of each struct member in order.
#each_pair {|member, value| ... }

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_a

Alias for #values.
#to_h ⇒ Hash

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

Alias for #inspect.
#values ⇒ Array (also: #to_a)

Returns the values for this struct as an Array.
#values_at(*indexes)

Returns the struct member values for each selector as an Array.
#initialize_copy(original) private

`Synchronization::AbstractStruct` - Included

#length	Returns the number of struct members.
#members	Returns the struct members as an array of symbols.
#size	Alias for Synchronization::AbstractStruct#length.
#initialize,
#ns_each	Yields the value of each struct member in order.
#ns_each_pair	Yields the name and value of each struct member in order.
#ns_equality	Equality.
#ns_get	Attribute Reference.
#ns_initialize_copy,
#ns_inspect	Describe the contents of this struct in a string.
#ns_merge	Returns a new struct containing the contents of `other` and the contents of `self`.
#ns_select	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`).
#ns_to_h	Returns a hash containing the names and values for the struct’s members.
#ns_values	Returns the values for this struct as an `Array`.
#ns_values_at	Returns the struct member values for each selector as an `Array`.
#pr_underscore

Class Method Details

.new(*args, &block) (private)

Factory for creating new struct classes.

“‘ new( [, member_name]+>) -> StructClass click to toggle source new( [, member_name]+>) {|StructClass| block } -> StructClass new(value, …) -> obj StructClass[value, …] -> obj “`

The first two forms are used to create a new struct subclass class_name that can contain a value for each member_name . This subclass can be used to create instances of the structure like any other Class .

If the class_name is omitted an anonymous struct class will be created. Otherwise, the name of this struct will appear as a constant in the struct class, so it must be unique for all structs under this base class and must start with a capital letter. Assigning a struct class to a constant also gives the class the name of the constant.

If a block is given it will be evaluated in the context of StructClass, passing the created class as a parameter. This is the recommended way to customize a struct. Subclassing an anonymous struct creates an extra anonymous class that will never be used.

The last two forms create a new instance of a struct subclass. The number of value parameters must be less than or equal to the number of attributes defined for the struct. Unset parameters default to nil. Passing more parameters than number of attributes will raise an ArgumentError.

Instance Method Details

#==(other) ⇒ `Boolean`

Equality

Returns:

(Boolean) —

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

[ GitHub ]

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

[ GitHub ]

# 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

[ GitHub ]

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

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)

[ GitHub ]

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

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)

[ GitHub ]

# 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

#initialize_copy(original) (private)

[ GitHub ]

# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 97


def initialize_copy(original)
  synchronize do
    super(original)
    ns_initialize_copy
  end
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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

# 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_a

Alias for #values.

[ GitHub ]

# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 21


alias_method :to_a, :values

#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

[ GitHub ]

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


def to_h
  synchronize { ns_to_h }
end

#to_s

Alias for #inspect.

[ GitHub ]

# File 'lib/concurrent-ruby/concurrent/settable_struct.rb', line 32


alias_method :to_s, :inspect

#values ⇒ Array Also known as: #to_a

Returns the values for this struct as an Array.

Returns:

(Array) —

the values for this struct

[ GitHub ]

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


def values
  synchronize { ns_values }
end

#values_at(*indexes)

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)

[ GitHub ]

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


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

Module: Concurrent::SettableStruct

Overview

Constant Summary

Class Method Summary

Instance Method Summary

Synchronization::AbstractStruct - Included

Class Method Details

.new(*args, &block) (private)

Instance Method Details

#==(other) ⇒ Boolean

#[](member) ⇒ Object

#[]=(member, value) ⇒ Object

#each {|value| ... }

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

#initialize_copy(original) (private)

#inspect ⇒ String Also known as: #to_s

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

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

#to_a

#to_h ⇒ Hash

#to_s

#values ⇒ Array Also known as: #to_a

#values_at(*indexes)

`Synchronization::AbstractStruct` - Included

#==(other) ⇒ `Boolean`

#inspect ⇒ `String` Also known as: #to_s