o-concurrent-ruby 1.1.11

data/lib/concurrent-ruby/concurrent/synchronization/object.rb

@@ -0,0 +1,183 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    ObjectImplementation = case
+                           when Concurrent.on_cruby?
+                             MriObject
+                           when Concurrent.on_jruby?
+                             JRubyObject
+                           when Concurrent.on_rbx?
+                             RbxObject
+                           when Concurrent.on_truffleruby?
+                             TruffleRubyObject
+                           else
+                             warn 'Possibly unsupported Ruby implementation'
+                             MriObject
+                           end
+    private_constant :ObjectImplementation
+
+    # Abstract object providing final, volatile, ans CAS extensions to build other concurrent abstractions.
+    # - final instance variables see {Object.safe_initialization!}
+    # - volatile instance variables see {Object.attr_volatile}
+    # - volatile instance variables see {Object.attr_atomic}
+    class Object < ObjectImplementation
+      # TODO make it a module if possible
+
+      # @!method self.attr_volatile(*names)
+      #   Creates methods for reading and writing (as `attr_accessor` does) to a instance variable with
+      #   volatile (Java) semantic. The instance variable should be accessed only through generated methods.
+      #
+      #   @param [::Array<Symbol>] names of the instance variables to be volatile
+      #   @return [::Array<Symbol>] names of defined method names
+
+      # Has to be called by children.
+      def initialize
+        super
+        __initialize_atomic_fields__
+      end
+
+      # By calling this method on a class, it and all its children are marked to be constructed safely. Meaning that
+      # all writes (ivar initializations) are made visible to all readers of newly constructed object. It ensures
+      # same behaviour as Java's final fields.
+      # @example
+      #   class AClass < Concurrent::Synchronization::Object
+      #     safe_initialization!
+      #
+      #     def initialize
+      #       @AFinalValue = 'value' # published safely, does not have to be synchronized
+      #     end
+      #   end
+      # @return [true]
+      def self.safe_initialization!
+        # define only once, and not again in children
+        return if safe_initialization?
+
+        # @!visibility private
+        def self.new(*args, &block)
+          object = super(*args, &block)
+        ensure
+          object.full_memory_barrier if object
+        end
+
+        @safe_initialization = true
+      end
+
+      # @return [true, false] if this class is safely initialized.
+      def self.safe_initialization?
+        @safe_initialization = false unless defined? @safe_initialization
+        @safe_initialization || (superclass.respond_to?(:safe_initialization?) && superclass.safe_initialization?)
+      end
+
+      # For testing purposes, quite slow. Injects assert code to new method which will raise if class instance contains
+      # any instance variables with CamelCase names and isn't {.safe_initialization?}.
+      # @raise when offend found
+      # @return [true]
+      def self.ensure_safe_initialization_when_final_fields_are_present
+        Object.class_eval do
+          def self.new(*args, &block)
+            object = super(*args, &block)
+          ensure
+            has_final_field = object.instance_variables.any? { |v| v.to_s =~ /^@[A-Z]/ }
+            if has_final_field && !safe_initialization?
+              raise "there was an instance of #{object.class} with final field but not marked with safe_initialization!"
+            end
+          end
+        end
+        true
+      end
+
+      # Creates methods for reading and writing to a instance variable with
+      # volatile (Java) semantic as {.attr_volatile} does.
+      # The instance variable should be accessed oly through generated methods.
+      # This method generates following methods: `value`, `value=(new_value) #=> new_value`,
+      # `swap_value(new_value) #=> old_value`,
+      # `compare_and_set_value(expected, value) #=> true || false`, `update_value(&block)`.
+      # @param [::Array<Symbol>] names of the instance variables to be volatile with CAS.
+      # @return [::Array<Symbol>] names of defined method names.
+      # @!macro attr_atomic
+      #   @!method $1
+      #     @return [Object] The $1.
+      #   @!method $1=(new_$1)
+      #     Set the $1.
+      #     @return [Object] new_$1.
+      #   @!method swap_$1(new_$1)
+      #     Set the $1 to new_$1 and return the old $1.
+      #     @return [Object] old $1
+      #   @!method compare_and_set_$1(expected_$1, new_$1)
+      #     Sets the $1 to new_$1 if the current $1 is expected_$1
+      #     @return [true, false]
+      #   @!method update_$1(&block)
+      #     Updates the $1 using the block.
+      #     @yield [Object] Calculate a new $1 using given (old) $1
+      #     @yieldparam [Object] old $1
+      #     @return [Object] new $1
+      def self.attr_atomic(*names)
+        @__atomic_fields__ ||= []
+        @__atomic_fields__ += names
+        safe_initialization!
+        define_initialize_atomic_fields
+
+        names.each do |name|
+          ivar = :"@Atomic#{name.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }}"
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              #{ivar}.get
+            end
+
+            def #{name}=(value)
+              #{ivar}.set value
+            end
+
+            def swap_#{name}(value)
+              #{ivar}.swap value
+            end
+
+            def compare_and_set_#{name}(expected, value)
+              #{ivar}.compare_and_set expected, value
+            end
+
+            def update_#{name}(&block)
+              #{ivar}.update(&block)
+            end
+          RUBY
+        end
+        names.flat_map { |n| [n, :"#{n}=", :"swap_#{n}", :"compare_and_set_#{n}", :"update_#{n}"] }
+      end
+
+      # @param [true, false] inherited should inherited volatile with CAS fields be returned?
+      # @return [::Array<Symbol>] Returns defined volatile with CAS fields on this class.
+      def self.atomic_attributes(inherited = true)
+        @__atomic_fields__ ||= []
+        ((superclass.atomic_attributes if superclass.respond_to?(:atomic_attributes) && inherited) || []) + @__atomic_fields__
+      end
+
+      # @return [true, false] is the attribute with name atomic?
+      def self.atomic_attribute?(name)
+        atomic_attributes.include? name
+      end
+
+      private
+
+      def self.define_initialize_atomic_fields
+        assignments = @__atomic_fields__.map do |name|
+          "@Atomic#{name.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }} = Concurrent::AtomicReference.new(nil)"
+        end.join("\n")
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def __initialize_atomic_fields__
+            super
+            #{assignments}
+          end
+        RUBY
+      end
+
+      private_class_method :define_initialize_atomic_fields
+
+      def __initialize_atomic_fields__
+      end
+
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization/rbx_lockable_object.rb

@@ -0,0 +1,71 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class RbxLockableObject < AbstractLockableObject
+      safe_initialization!
+
+      def initialize(*defaults)
+        super(*defaults)
+        @__Waiters__ = []
+        @__owner__   = nil
+      end
+
+      def initialize_copy(other)
+        super
+        @__Waiters__ = []
+        @__owner__   = nil
+      end
+
+      protected
+
+      def synchronize(&block)
+        if @__owner__ == Thread.current
+          yield
+        else
+          result = nil
+          Rubinius.synchronize(self) do
+            begin
+              @__owner__ = Thread.current
+              result     = yield
+            ensure
+              @__owner__ = nil
+            end
+          end
+          result
+        end
+      end
+
+      def ns_wait(timeout = nil)
+        wchan = Rubinius::Channel.new
+
+        begin
+          @__Waiters__.push wchan
+          Rubinius.unlock(self)
+          signaled = wchan.receive_timeout timeout
+        ensure
+          Rubinius.lock(self)
+
+          if !signaled && !@__Waiters__.delete(wchan)
+            # we timed out, but got signaled afterwards,
+            # so pass that signal on to the next waiter
+            @__Waiters__.shift << true unless @__Waiters__.empty?
+          end
+        end
+
+        self
+      end
+
+      def ns_signal
+        @__Waiters__.shift << true unless @__Waiters__.empty?
+        self
+      end
+
+      def ns_broadcast
+        @__Waiters__.shift << true until @__Waiters__.empty?
+        self
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization/rbx_object.rb

@@ -0,0 +1,49 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    module RbxAttrVolatile
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        def attr_volatile(*names)
+          names.each do |name|
+            ivar = :"@volatile_#{name}"
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                Rubinius.memory_barrier
+                #{ivar}
+              end
+
+              def #{name}=(value)
+                #{ivar} = value
+                Rubinius.memory_barrier
+              end
+            RUBY
+          end
+          names.map { |n| [n, :"#{n}="] }.flatten
+        end
+
+      end
+
+      def full_memory_barrier
+        # Rubinius instance variables are not volatile so we need to insert barrier
+        # TODO (pitr 26-Nov-2015): check comments like ^
+        Rubinius.memory_barrier
+      end
+    end
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class RbxObject < AbstractObject
+      include RbxAttrVolatile
+
+      def initialize
+        # nothing to do
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization/truffleruby_object.rb

@@ -0,0 +1,47 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    module TruffleRubyAttrVolatile
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def attr_volatile(*names)
+          names.each do |name|
+            ivar = :"@volatile_#{name}"
+
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                full_memory_barrier
+                #{ivar}                  
+              end
+
+              def #{name}=(value)
+                #{ivar} = value
+                full_memory_barrier
+              end
+            RUBY
+          end
+
+          names.map { |n| [n, :"#{n}="] }.flatten
+        end
+      end
+
+      def full_memory_barrier
+        TruffleRuby.full_memory_barrier
+      end
+    end
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class TruffleRubyObject < AbstractObject
+      include TruffleRubyAttrVolatile
+
+      def initialize
+        # nothing to do
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization/volatile.rb

@@ -0,0 +1,36 @@
+module Concurrent
+  module Synchronization
+
+    # Volatile adds the attr_volatile class method when included.
+    #
+    # @example
+    #   class Foo
+    #     include Concurrent::Synchronization::Volatile
+    #
+    #     attr_volatile :bar
+    #
+    #     def initialize
+    #       self.bar = 1
+    #     end
+    #   end
+    #
+    #  foo = Foo.new
+    #  foo.bar
+    #  => 1
+    #  foo.bar = 2
+    #  => 2
+
+    Volatile = case
+               when Concurrent.on_cruby?
+                 MriAttrVolatile
+               when Concurrent.on_jruby?
+                 JRubyAttrVolatile
+               when Concurrent.on_rbx?
+                 RbxAttrVolatile
+               when Concurrent.on_truffleruby?
+                 TruffleRubyAttrVolatile
+               else
+                 MriAttrVolatile
+               end
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization.rb

@@ -0,0 +1,30 @@
+require 'concurrent/utility/engine'
+
+require 'concurrent/synchronization/abstract_object'
+require 'concurrent/utility/native_extension_loader' # load native parts first
+Concurrent.load_native_extensions
+
+require 'concurrent/synchronization/mri_object'
+require 'concurrent/synchronization/jruby_object'
+require 'concurrent/synchronization/rbx_object'
+require 'concurrent/synchronization/truffleruby_object'
+require 'concurrent/synchronization/object'
+require 'concurrent/synchronization/volatile'
+
+require 'concurrent/synchronization/abstract_lockable_object'
+require 'concurrent/synchronization/mutex_lockable_object'
+require 'concurrent/synchronization/jruby_lockable_object'
+require 'concurrent/synchronization/rbx_lockable_object'
+
+require 'concurrent/synchronization/lockable_object'
+
+require 'concurrent/synchronization/condition'
+require 'concurrent/synchronization/lock'
+
+module Concurrent
+  # {include:file:docs-source/synchronization.md}
+  # {include:file:docs-source/synchronization-notes.md}
+  module Synchronization
+  end
+end
+

data/lib/concurrent-ruby/concurrent/thread_safe/synchronized_delegator.rb

@@ -0,0 +1,50 @@
+require 'delegate'
+require 'monitor'
+
+module Concurrent
+  unless defined?(SynchronizedDelegator)
+
+    # This class provides a trivial way to synchronize all calls to a given object
+    # by wrapping it with a `Delegator` that performs `Monitor#enter/exit` calls
+    # around the delegated `#send`. Example:
+    #
+    #   array = [] # not thread-safe on many impls
+    #   array = SynchronizedDelegator.new([]) # thread-safe
+    #
+    # A simple `Monitor` provides a very coarse-grained way to synchronize a given
+    # object, in that it will cause synchronization for methods that have no need
+    # for it, but this is a trivial way to get thread-safety where none may exist
+    # currently on some implementations.
+    #
+    # This class is currently being considered for inclusion into stdlib, via
+    # https://bugs.ruby-lang.org/issues/8556
+    #
+    # @!visibility private
+    class SynchronizedDelegator < SimpleDelegator
+      def setup
+        @old_abort = Thread.abort_on_exception
+        Thread.abort_on_exception = true
+      end
+
+      def teardown
+        Thread.abort_on_exception = @old_abort
+      end
+
+      def initialize(obj)
+        __setobj__(obj)
+        @monitor = Monitor.new
+      end
+
+      def method_missing(method, *args, &block)
+        monitor = @monitor
+        begin
+          monitor.enter
+          super
+        ensure
+          monitor.exit
+        end
+      end
+
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/thread_safe/util/adder.rb

@@ -0,0 +1,74 @@
+require 'concurrent/thread_safe/util'
+require 'concurrent/thread_safe/util/striped64'
+
+module Concurrent
+
+  # @!visibility private
+  module ThreadSafe
+    
+    # @!visibility private
+    module Util
+
+      # A Ruby port of the Doug Lea's jsr166e.LondAdder class version 1.8
+      # available in public domain.
+      #
+      # Original source code available here:
+      # http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/jsr166e/LongAdder.java?revision=1.8
+      #
+      # One or more variables that together maintain an initially zero
+      # sum. When updates (method +add+) are contended across threads,
+      # the set of variables may grow dynamically to reduce contention.
+      # Method +sum+ returns the current total combined across the
+      # variables maintaining the sum.
+      #
+      # This class is usually preferable to single +Atomic+ reference when
+      # multiple threads update a common sum that is used for purposes such
+      # as collecting statistics, not for fine-grained synchronization
+      # control.  Under low update contention, the two classes have similar
+      # characteristics. But under high contention, expected throughput of
+      # this class is significantly higher, at the expense of higher space
+      # consumption.
+      # 
+      # @!visibility private
+      class Adder < Striped64
+        # Adds the given value.
+        def add(x)
+          if (current_cells = cells) || !cas_base_computed {|current_base| current_base + x}
+            was_uncontended = true
+            hash            = hash_code
+            unless current_cells && (cell = current_cells.volatile_get_by_hash(hash)) && (was_uncontended = cell.cas_computed {|current_value| current_value + x})
+              retry_update(x, hash, was_uncontended) {|current_value| current_value + x}
+            end
+          end
+        end
+
+        def increment
+          add(1)
+        end
+
+        def decrement
+          add(-1)
+        end
+
+        # Returns the current sum.  The returned value is _NOT_ an
+        # atomic snapshot: Invocation in the absence of concurrent
+        # updates returns an accurate result, but concurrent updates that
+        # occur while the sum is being calculated might not be
+        # incorporated.
+        def sum
+          x = base
+          if current_cells = cells
+            current_cells.each do |cell|
+              x += cell.value if cell
+            end
+          end
+          x
+        end
+
+        def reset
+          internal_reset(0)
+        end
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/thread_safe/util/cheap_lockable.rb

@@ -0,0 +1,118 @@
+require 'concurrent/thread_safe/util'
+require 'concurrent/thread_safe/util/volatile'
+
+module Concurrent
+
+  # @!visibility private
+  module ThreadSafe
+
+    # @!visibility private
+    module Util
+
+      # Provides a cheapest possible (mainly in terms of memory usage) +Mutex+
+      # with the +ConditionVariable+ bundled in.
+      #
+      # Usage:
+      #   class A
+      #     include CheapLockable
+      #
+      #     def do_exlusively
+      #       cheap_synchronize { yield }
+      #     end
+      #
+      #     def wait_for_something
+      #       cheap_synchronize do
+      #         cheap_wait until resource_available?
+      #         do_something
+      #         cheap_broadcast # wake up others
+      #       end
+      #     end
+      #   end
+      # 
+      # @!visibility private
+      module CheapLockable
+        private
+        engine = defined?(RUBY_ENGINE) && RUBY_ENGINE
+        if engine == 'rbx'
+          # Making use of the Rubinius' ability to lock via object headers to avoid the overhead of the extra Mutex objects.
+          def cheap_synchronize
+            Rubinius.lock(self)
+            begin
+              yield
+            ensure
+              Rubinius.unlock(self)
+            end
+          end
+
+          def cheap_wait
+            wchan = Rubinius::Channel.new
+
+            begin
+              waiters = @waiters ||= []
+              waiters.push wchan
+              Rubinius.unlock(self)
+              signaled = wchan.receive_timeout nil
+            ensure
+              Rubinius.lock(self)
+
+              unless signaled or waiters.delete(wchan)
+                # we timed out, but got signaled afterwards (e.g. while waiting to
+                # acquire @lock), so pass that signal on to the next waiter
+                waiters.shift << true unless waiters.empty?
+              end
+            end
+
+            self
+          end
+
+          def cheap_broadcast
+            waiters = @waiters ||= []
+            waiters.shift << true until waiters.empty?
+            self
+          end
+        elsif engine == 'jruby'
+          # Use Java's native synchronized (this) { wait(); notifyAll(); } to avoid the overhead of the extra Mutex objects
+          require 'jruby'
+
+          def cheap_synchronize
+            JRuby.reference0(self).synchronized { yield }
+          end
+
+          def cheap_wait
+            JRuby.reference0(self).wait
+          end
+
+          def cheap_broadcast
+            JRuby.reference0(self).notify_all
+          end
+        else
+          require 'thread'
+
+          extend Volatile
+          attr_volatile :mutex
+
+          # Non-reentrant Mutex#syncrhonize
+          def cheap_synchronize
+            true until (my_mutex = mutex) || cas_mutex(nil, my_mutex = Mutex.new)
+            my_mutex.synchronize { yield }
+          end
+
+          # Releases this object's +cheap_synchronize+ lock and goes to sleep waiting for other threads to +cheap_broadcast+, reacquires the lock on wakeup.
+          # Must only be called in +cheap_broadcast+'s block.
+          def cheap_wait
+            conditional_variable = @conditional_variable ||= ConditionVariable.new
+            conditional_variable.wait(mutex)
+          end
+
+          # Wakes up all threads waiting for this object's +cheap_synchronize+ lock.
+          # Must only be called in +cheap_broadcast+'s block.
+          def cheap_broadcast
+            if conditional_variable = @conditional_variable
+              conditional_variable.broadcast
+            end
+          end
+        end
+      end
+    end
+  end
+end