lib/concurrent-ruby/concurrent/mutable_struct.rb
require 'concurrent/synchronization/abstract_struct' require 'concurrent/synchronization/lockable_object' module Concurrent # 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 http://ruby-doc.org/core/Struct.html Ruby standard library `Struct` module MutableStruct include Synchronization::AbstractStruct # @!macro struct_new # # 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 http://ruby-doc.org/core/Struct.html#method-c-new Ruby standard library `Struct#new` # @!macro struct_values # # Returns the values for this struct as an Array. # # @return [Array] the values for this struct # def values synchronize { ns_values } end alias_method :to_a, :values # @!macro struct_values_at # # 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`). # # @param [Fixnum, Range] indexes the index(es) from which to obatin the values (in order) def values_at(*indexes) synchronize { ns_values_at(indexes) } end # @!macro struct_inspect # # Describe the contents of this struct in a string. # # @return [String] the contents of this struct in a string def inspect synchronize { ns_inspect } end alias_method :to_s, :inspect # @!macro struct_merge # # 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`. # # @param [Hash] other the hash from which to set the new values # @yield an options block for resolving duplicate keys # @yieldparam [String, Symbol] member the name of the member which is duplicated # @yieldparam [Object] selfvalue the value of the member in `self` # @yieldparam [Object] othervalue the value of the member in `other` # # @return [Synchronization::AbstractStruct] a new struct with the new values # # @raise [ArgumentError] of given a member that is not defined in the struct def merge(other, &block) synchronize { ns_merge(other, &block) } end # @!macro struct_to_h # # Returns a hash containing the names and values for the struct’s members. # # @return [Hash] the names and values for the struct’s members def to_h synchronize { ns_to_h } end # @!macro struct_get # # Attribute Reference # # @param [Symbol, String, Integer] member the string or symbol name of the member # for which to obtain the value or the member's index # # @return [Object] the value of the given struct member or the member at the given index. # # @raise [NameError] if the member does not exist # @raise [IndexError] if the index is out of range. def [](member) synchronize { ns_get(member) } end # @!macro struct_equality # # Equality # # @return [Boolean] true if other has the same struct subclass and has # equal member values (according to `Object#==`) def ==(other) synchronize { ns_equality(other) } end # @!macro struct_each # # Yields the value of each struct member in order. If no block is given # an enumerator is returned. # # @yield the operation to be performed on each struct member # @yieldparam [Object] value each struct value (in order) def each(&block) return enum_for(:each) unless block_given? synchronize { ns_each(&block) } end # @!macro struct_each_pair # # Yields the name and value of each struct member in order. If no block is # given an enumerator is returned. # # @yield the operation to be performed on each struct member/value pair # @yieldparam [Object] member each struct member (in order) # @yieldparam [Object] value each struct value (in order) def each_pair(&block) return enum_for(:each_pair) unless block_given? synchronize { ns_each_pair(&block) } end # @!macro struct_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`). # # @yield the operation to be performed on each struct member # @yieldparam [Object] value each struct value (in order) # # @return [Array] an array containing each value for which the block returns true def select(&block) return enum_for(:select) unless block_given? synchronize { ns_select(&block) } end # @!macro struct_set # # Attribute Assignment # # Sets the value of the given struct member or the member at the given index. # # @param [Symbol, String, Integer] member the string or symbol name of the member # for which to obtain the value or the member's index # # @return [Object] the value of the given struct member or the member at the given index. # # @raise [NameError] if the name does not exist # @raise [IndexError] if the index is out of range. 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 private # @!visibility private def initialize_copy(original) synchronize do super(original) ns_initialize_copy end end # @!macro struct_new 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 FACTORY = Class.new(Synchronization::LockableObject) do def define_struct(name, members, &block) synchronize do clazz = Synchronization::AbstractStruct.define_struct_class(MutableStruct, Synchronization::LockableObject, name, members, &block) members.each_with_index do |member, index| clazz.send :remove_method, member clazz.send(:define_method, member) do synchronize { @values[index] } end clazz.send(:define_method, "#{member}=") do |value| synchronize { @values[index] = value } end end clazz end end end.new private_constant :FACTORY end end