Merge pull request #294 from ruby-concurrency/safe-struct

Thread-safe Struct variants:

* ImmutableStruct
* MutableStruct
* SettableStruct

Author: jdantonio

README.md

@@ -63,6 +63,12 @@ This library contains a variety of concurrency abstractions at high and low leve
 
 * See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
 
+* Thread-safe structure classes derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html)
+
+* `ImmutableStruct` Immutable struct where values are set at construction and cannot be changed later.
+* `MutableStruct` Synchronized, mutable struct where values can be safely changed at any time.
+* `SettableStruct` Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
+
 ### Thread synchronization classes and algorithms
 
 * [CountdownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)

examples/benchmark_structs.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'benchmark'
+require 'concurrent'
+
+n = 500_000
+
+StructPair = Struct.new(:left, :right)
+SafePair = Concurrent::MutableStruct.new(:left, :right)
+FinalPair = Concurrent::SettableStruct.new(:left, :right)
+ImmutablePair = Concurrent::ImmutableStruct.new(:left, :right)
+
+array_pair = [true, false].freeze
+struct_pair = StructPair.new(true, false)
+safe_pair = SafePair.new(true, false)
+final_pair = FinalPair.new(true, false)
+immutable = ImmutablePair.new(true, false)
+
+puts "Object creation...\n"
+Benchmark.bmbm do |x|
+  x.report('create frozen array') { n.times{ [true, false].freeze } }
+  x.report('create frozen struct') { n.times{ StructPair.new(true, false).freeze } }
+  x.report('create mutable struct') { n.times{ SafePair.new(true, false) } }
+  x.report('create settable struct') { n.times{ FinalPair.new(true, false) } }
+  x.report('create immutable struct') { n.times{ ImmutablePair.new(true, false) } }
+end
+
+puts "\n"
+
+puts "Object access...\n"
+Benchmark.bmbm do |x|
+  x.report('read from frozen array') { n.times{ array_pair.last } }
+  x.report('read from frozen struct') { n.times{ struct_pair.right } }
+  x.report('read from mutable struct') { n.times{ safe_pair.right } }
+  x.report('read from settable struct') { n.times{ final_pair.right } }
+  x.report('read from immutable struct') { n.times{ immutable.right } }
+end
+
+puts "\n"
+
+puts "Enumeration...\n"
+Benchmark.bmbm do |x|
+  x.report('iterate over frozen array') { n.times{ array_pair.each{ nil } } }
+  x.report('iterate over frozen struct') { n.times{ struct_pair.each{ nil } } }
+  x.report('iterate over mutable struct') { n.times{ safe_pair.each{ nil } } }
+  x.report('iterate over settable struct') { n.times{ final_pair.each{ nil } } }
+  x.report('iterate over immutable struct') { n.times{ immutable.each{ nil } } }
+end
+
+__END__
+
+Object creation...
+Rehearsal -----------------------------------------------------------
+create frozen array       0.090000   0.000000   0.090000 (  0.091262)
+create frozen struct      0.180000   0.000000   0.180000 (  0.179993)
+create mutable struct     2.030000   0.000000   2.030000 (  2.052071)
+create settable struct    2.070000   0.000000   2.070000 (  2.080022)
+create immutable struct   0.710000   0.000000   0.710000 (  0.716877)
+-------------------------------------------------- total: 5.080000sec
+
+                              user     system      total        real
+create frozen array       0.100000   0.000000   0.100000 (  0.097776)
+create frozen struct      0.190000   0.000000   0.190000 (  0.186287)
+create mutable struct     2.020000   0.010000   2.030000 (  2.032391)
+create settable struct    2.030000   0.000000   2.030000 (  2.031631)
+create immutable struct   0.690000   0.000000   0.690000 (  0.695010)
+
+Object access...
+Rehearsal --------------------------------------------------------------
+read from frozen array       0.060000   0.000000   0.060000 (  0.060430)
+read from frozen struct      0.060000   0.000000   0.060000 (  0.058978)
+read from mutable struct     0.440000   0.000000   0.440000 (  0.454071)
+read from settable struct    0.460000   0.000000   0.460000 (  0.457699)
+read from immutable struct   0.120000   0.000000   0.120000 (  0.126701)
+----------------------------------------------------- total: 1.140000sec
+
+                                 user     system      total        real
+read from frozen array       0.060000   0.000000   0.060000 (  0.063006)
+read from frozen struct      0.060000   0.000000   0.060000 (  0.094203)
+read from mutable struct     0.420000   0.000000   0.420000 (  0.468304)
+read from settable struct    0.410000   0.000000   0.410000 (  0.452446)
+read from immutable struct   0.110000   0.010000   0.120000 (  0.127030)
+
+Enumeration...
+Rehearsal -----------------------------------------------------------------
+iterate over frozen array       0.170000   0.000000   0.170000 (  0.176898)
+iterate over frozen struct      0.160000   0.000000   0.160000 (  0.160786)
+iterate over mutable struct     1.520000   0.000000   1.520000 (  1.627013)
+iterate over settable struct    1.500000   0.010000   1.510000 (  1.525163)
+iterate over immutable struct   0.990000   0.000000   0.990000 (  1.006201)
+-------------------------------------------------------- total: 4.350000sec
+
+                                    user     system      total        real
+iterate over frozen array       0.170000   0.000000   0.170000 (  0.167927)
+iterate over frozen struct      0.150000   0.000000   0.150000 (  0.157328)
+iterate over mutable struct     1.450000   0.000000   1.450000 (  1.462654)
+iterate over settable struct    1.460000   0.000000   1.460000 (  1.480270)
+iterate over immutable struct   0.940000   0.010000   0.950000 (  0.955633)

lib/concurrent.rb

@@ -10,6 +10,7 @@
 require 'concurrent/errors'
 require 'concurrent/executors'
 require 'concurrent/utilities'
+require 'concurrent/struct'
 
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/async'

lib/concurrent/atomic/atomic_fixnum.rb

@@ -32,7 +32,7 @@ class MutexAtomicFixnum < Synchronization::Object
     #
     #   Creates a new `AtomicFixnum` with the given initial value.
     #
-    #   @param [Fixnum] init the initial value
+    #   @param [Fixnum] initial the initial value
     #   @raise [ArgumentError] if the initial value is not a `Fixnum`
     def initialize(initial = 0)
       super(initial)

lib/concurrent/errors.rb

@@ -7,6 +7,9 @@ module Concurrent
   # sequence or when the object is in an inappropriate state.
   LifecycleError = Class.new(StandardError)
 
+  # Raised when an attempt is made to violate an immutability guarantee.
+  ImmutabilityError = Class.new(StandardError)
+
   # Raised when an object's methods are called when it has not been
   # properly initialized.
   InitializationError = Class.new(StandardError)

lib/concurrent/struct.rb

@@ -0,0 +1,3 @@
+require 'concurrent/struct/immutable_struct'
+require 'concurrent/struct/mutable_struct'
+require 'concurrent/struct/settable_struct'

lib/concurrent/struct/abstract_struct.rb

@@ -0,0 +1,148 @@
+module Concurrent
+
+  # @!visibility private
+  module AbstractStruct
+
+    # @!macro [attach] struct_length
+    #
+    #   Returns the number of struct members.
+    #
+    #   @return [Fixnum] the number of struct members
+    def length
+      self.class::MEMBERS.length
+    end
+    alias_method :size, :length
+
+    # @!macro [attach] struct_members
+    #
+    #   Returns the struct members as an array of symbols.
+    #
+    #   @return [Array] the struct members as an array of symbols
+    def members
+      self.class::MEMBERS.dup
+    end
+
+    protected
+
+    # @!macro struct_values
+    #
+    # @!visibility private
+    def ns_values
+      @values.dup
+    end
+
+    # @!macro struct_values_at
+    #
+    # @!visibility private
+    def ns_values_at(indexes)
+      @values.values_at(*indexes)
+    end
+
+    # @!macro struct_to_h
+    #
+    # @!visibility private
+    def ns_to_h
+      length.times.reduce({}){|memo, i| memo[self.class::MEMBERS[i]] = @values[i]; memo}
+    end
+
+    # @!macro struct_get
+    #
+    # @!visibility private
+    def ns_get(member)
+      if member.is_a? Integer
+        if member >= @values.length
+          raise IndexError.new("offset #{member} too large for struct(size:#{@values.length})")
+        end
+        @values[member]
+      else
+        send(member)
+      end
+    rescue NoMethodError
+      raise NameError.new("no member '#{member}' in struct")
+    end
+
+    # @!macro struct_equality
+    #
+    # @!visibility private
+    def ns_equality(other)
+      self.class == other.class && self.values == other.values
+    end
+
+    # @!macro struct_each
+    #
+    # @!visibility private
+    def ns_each
+      values.each{|value| yield value }
+    end
+
+    # @!macro struct_each_pair
+    #
+    # @!visibility private
+    def ns_each_pair
+      @values.length.times do |index|
+        yield self.class::MEMBERS[index], @values[index]
+      end
+    end
+
+    # @!macro struct_select
+    #
+    # @!visibility private
+    def ns_select
+      values.select{|value| yield value }
+    end
+
+    # @!macro struct_inspect
+    #
+    # @!visibility private
+    def ns_inspect
+      struct = pr_underscore(self.class.ancestors[1])
+      clazz = ((self.class.to_s =~ /^#<Class:/) == 0) ? '' : " #{self.class}"
+      "#<#{struct}#{clazz} #{ns_to_h}>"
+    end
+
+    # @!macro struct_merge
+    #
+    # @!visibility private
+    def ns_merge(other, &block)
+      self.class.new(*self.to_h.merge(other, &block).values)
+    end
+
+    # @!visibility private
+    def pr_underscore(clazz)
+      word = clazz.to_s
+      word.gsub!(/::/, '/')
+      word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    # @!visibility private
+    def self.define_struct_class(parent, base, name, members, &block)
+      clazz = Class.new(base || Object) do
+        include parent
+        self.const_set(:MEMBERS, members.collect{|member| member.to_s.to_sym}.freeze) 
+        def ns_initialize(*values)
+          raise ArgumentError.new('struct size differs') if values.length > length
+          @values = values.fill(nil, values.length..length-1)
+        end
+      end
+      unless name.nil?
+        begin
+          parent.const_set(name, clazz)
+          parent.const_get(name)
+        rescue NameError
+          raise NameError.new("identifier #{name} needs to be constant") 
+        end
+      end
+      members.each_with_index do |member, index|
+        clazz.send(:define_method, member) do
+          @values[index]
+        end
+      end
+      clazz.class_exec(&block) unless block.nil?
+      clazz
+    end
+  end
+end

lib/concurrent/struct/immutable_struct.rb

@@ -0,0 +1,92 @@
+require 'concurrent/struct/abstract_struct'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # A thread-safe, immutable variation of Ruby's standard `Struct`.
+  #
+  # @see http://ruby-doc.org/core-2.2.0/Struct.html Ruby standard library `Struct`
+  module ImmutableStruct
+    include AbstractStruct
+
+    # @!visibility private
+    def initialize(*values)
+      ns_initialize(*values)
+    end
+
+    # @!macro struct_values
+    def values
+      ns_values
+    end
+    alias_method :to_a, :values
+
+    # @!macro struct_values_at
+    def values_at(*indexes)
+      ns_values_at(indexes)
+    end
+
+    # @!macro struct_inspect
+    def inspect
+      ns_inspect
+    end
+    alias_method :to_s, :inspect
+
+    # @!macro struct_merge
+    def merge(other, &block)
+      ns_merge(other, &block)
+    end
+
+    # @!macro struct_to_h
+    def to_h
+      ns_to_h
+    end
+
+    # @!macro struct_get
+    def [](member)
+      ns_get(member)
+    end
+
+    # @!macro struct_equality
+    def ==(other)
+      ns_equality(other)
+    end
+
+    # @!macro struct_each
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      ns_each(&block)
+    end
+
+    # @!macro struct_each_pair
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+      ns_each_pair(&block)
+    end
+
+    # @!macro struct_select
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      ns_select(&block)
+    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::Object) do
+      def define_struct(name, members, &block)
+        synchronize do
+          AbstractStruct.define_struct_class(ImmutableStruct, nil, name, members, &block)
+        end
+      end
+    end.new
+    private_constant :FACTORY
+  end
+end