Module: Concurrent::MutableStruct — Concurrent

Class List Method List File List

# Module: Concurrent::MutableStruct

Defined in:
  lib/concurrent/mutable_struct.rb

## Overview

An thread-safe variation of Ruby's standard `Struct`. Values can be set at construction or safely changed at any time during the object's lifecycle.

See Also:

- Ruby standard library `Struct`

## Constant Summary

## Class Method Summary (collapse)

- + (undocumented) new(*args, &block)

  Factory for creating new struct classes.

## Instance Method Summary (collapse)

- - (Boolean) ==(other)

  Equality.

- - (Object) [](member)

  Attribute Reference.

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

  Attribute Assignment.

- - (undocumented) each {|value| ... }

  Yields the value of each struct member in order.

- - (undocumented) each_pair {|member, value| ... }

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

- - (String) inspect (also: #to_s)

  Describe the contents of this struct in a string.

- - (Fixnum) length (also: #size) included from Synchronization::AbstractStruct

  Returns the number of struct members.

- - (Array) members included from Synchronization::AbstractStruct

  Returns the struct members as an array of symbols.

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

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

- - (Array) select {|value| ... }

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

- - (Hash) to_h

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

- - (Array) values (also: #to_a)

  Returns the values for this struct as an Array.

- - (undocumented) values_at(*indexes)

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

## Class Method Details

### + (`undocumented`) new(*args, &block)

Factory for creating new struct classes.

    new([class_name] [, member_name]+>) -> StructClass click to toggle source
    new([class_name] [, 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`.

See Also:

- Ruby standard library `Struct#new`

    200
    201
    202
    203
    204
    205
    206
    207
    208
    # File 'lib/concurrent/mutable_struct.rb', line 200

    def self.new(*args, &block)
      clazz_name = nil
      if args.length == 0
        raise ArgumentError.new('wrong number of arguments (0 for 1+)')
      elsif args.length > 0 && args.first.is_a?(String)
        clazz_name = args.shift
      end
      FACTORY.define_struct(clazz_name, args, &block)
    end

## Instance Method Details

### - (`Boolean`) ==(other)

Equality

Returns:

- (`Boolean`) —

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

    128
    129
    130
    # File 'lib/concurrent/mutable_struct.rb', line 128

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

### - (`Object`) [](member)

Attribute Reference

Parameters:

- member (`Symbol`, `String`, `Integer`) —

  the string or symbol name of the memeber 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.

    118
    119
    120
    # File 'lib/concurrent/mutable_struct.rb', line 118

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

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

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

    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    # File 'lib/concurrent/mutable_struct.rb', line 185

    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 { @values[member] = value }
      else
        send("#{member}=", value)
      end
    rescue NoMethodError
      raise NameError.new("no member '#{member}' in struct")
    end

### - (`undocumented`) 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)

    139
    140
    141
    142
    # File 'lib/concurrent/mutable_struct.rb', line 139

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

### - (`undocumented`) 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)

    152
    153
    154
    155
    # File 'lib/concurrent/mutable_struct.rb', line 152

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

### - (`String`) inspect Also known as: to_s

Describe the contents of this struct in a string.

Returns:

- (`String`) —

  the contents of this struct in a string

    72
    73
    74
    # File 'lib/concurrent/mutable_struct.rb', line 72

    def inspect
      synchronize { ns_inspect }
    end

### - (`Fixnum`) length Also known as: size Originally defined in module Synchronization::AbstractStruct

Returns the number of struct members.

Returns:

- (`Fixnum`) —

  the number of struct members

### - (`Array`) members Originally defined in module Synchronization::AbstractStruct

Returns the struct members as an array of symbols.

Returns:

- (`Array`) —

  the struct members as an array of symbols

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

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

    94
    95
    96
    # File 'lib/concurrent/mutable_struct.rb', line 94

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

### - (`Array`) select {|value| ... }

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

    167
    168
    169
    170
    # File 'lib/concurrent/mutable_struct.rb', line 167

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

### - (`Hash`) to_h

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

Returns:

- (`Hash`) —

  the names and values for the struct’s members

    103
    104
    105
    # File 'lib/concurrent/mutable_struct.rb', line 103

    def to_h
      synchronize { ns_to_h }
    end

### - (`Array`) values Also known as: to_a

Returns the values for this struct as an Array.

Returns:

- (`Array`) —

  the values for this struct

    51
    52
    53
    # File 'lib/concurrent/mutable_struct.rb', line 51

    def values
      synchronize { ns_values }
    end

### - (`undocumented`) 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)

    63
    64
    65
    # File 'lib/concurrent/mutable_struct.rb', line 63

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