concurrent-ruby 1.0.0.pre4 → 1.0.0.pre5

data/lib/concurrent/synchronization/lockable_object.rb

@@ -8,9 +8,9 @@ module Concurrent
                                      MriMonitorLockableObject
                                    when Concurrent.on_cruby? && Concurrent.ruby_version(:>, 1, 9, 3)
                                      MriMutexLockableObject
-                                   when defined? JRubyLockableObject
+                                   when Concurrent.on_jruby?
                                      JRubyLockableObject
-                                   when Concurrent.on_rbx?
+                                   when Concurrent.on_rbx? || Concurrent.on_truffle?
                                      RbxLockableObject
                                    else
                                      warn 'Possibly unsupported Ruby implementation'
@@ -18,20 +18,36 @@ module Concurrent
                                    end
     private_constant :LockableObjectImplementation
 
-    # TODO (pitr 12-Sep-2015): make private for c-r, prohibit subclassing
+    #   Safe synchronization under any Ruby implementation.
+    #   It provides methods like {#synchronize}, {#wait}, {#signal} and {#broadcast}.
+    #   Provides a single layer which can improve its implementation over time without changes needed to
+    #   the classes using it. Use {Synchronization::Object} not this abstract class.
+    #
+    #   @note this object does not support usage together with
+    #     [`Thread#wakeup`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-wakeup)
+    #     and [`Thread#raise`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-raise).
+    #     `Thread#sleep` and `Thread#wakeup` will work as expected but mixing `Synchronization::Object#wait` and
+    #     `Thread#wakeup` will not work on all platforms.
+    #
+    #   @see {Event} implementation as an example of this class use
+    #
+    #   @example simple
+    #     class AnClass < Synchronization::Object
+    #       def initialize
+    #         super
+    #         synchronize { @value = 'asd' }
+    #       end
+    #
+    #       def value
+    #         synchronize { @value }
+    #       end
+    #     end
+    #
+    # @!visibility private
     class LockableObject < LockableObjectImplementation
 
+      # TODO (pitr 12-Sep-2015): make private for c-r, prohibit subclassing
       # TODO (pitr 12-Sep-2015): we inherit too much ourselves :/
-      def self.allow_only_direct_descendants!
-        this = self
-        singleton_class.send :define_method, :inherited do |child|
-          # super child
-
-          if child.superclass != this
-            warn "all children of #{this} are final, subclassing is not supported use composition."
-          end
-        end
-      end
 
       # @!method initialize(*args, &block)
       #   @!macro synchronization_object_method_initialize
@@ -39,9 +55,6 @@ module Concurrent
       # @!method synchronize
       #   @!macro synchronization_object_method_synchronize
 
-      # @!method initialize(*args, &block)
-      #   @!macro synchronization_object_method_ns_initialize
-
       # @!method wait_until(timeout = nil, &condition)
       #   @!macro synchronization_object_method_ns_wait_until
 

data/lib/concurrent/synchronization/mri_object.rb

@@ -1,35 +1,43 @@
 module Concurrent
   module Synchronization
 
-    # @!visibility private
-    # @!macro internal_implementation_note
-    class MriObject < AbstractObject
+    module MriAttrVolatile
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
 
-      def initialize
-        # nothing to do
+      module ClassMethods
+        def attr_volatile(*names)
+          names.each do |name|
+            ivar = :"@volatile_#{name}"
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                #{ivar}
+              end
+
+              def #{name}=(value)
+                #{ivar} = value
+              end
+            RUBY
+          end
+          names.map { |n| [n, :"#{n}="] }.flatten
+        end
       end
 
       def full_memory_barrier
         # relying on undocumented behavior of CRuby, GVL acquire has lock which ensures visibility of ivars
         # https://github.com/ruby/ruby/blob/ruby_2_2/thread_pthread.c#L204-L211
       end
+    end
 
-      def self.attr_volatile(*names)
-        names.each do |name|
-          ivar = :"@volatile_#{name}"
-          class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}
-          #{ivar}
-            end
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class MriObject < AbstractObject
+      include MriAttrVolatile
 
-            def #{name}=(value)
-              #{ivar} = value
-            end
-          RUBY
-        end
-        names.map { |n| [n, :"#{n}="] }.flatten
+      def initialize
+        # nothing to do
       end
     end
-
   end
 end

data/lib/concurrent/synchronization/object.rb

@@ -6,52 +6,32 @@ module Concurrent
     ObjectImplementation = case
                            when Concurrent.on_cruby?
                              MriObject
-                           when defined? JRubyObject
+                           when Concurrent.on_jruby?
                              JRubyObject
-                           when Concurrent.on_rbx?
+                           when Concurrent.on_rbx? || Concurrent.on_truffle?
                              RbxObject
                            else
-                             warn 'Possibly unsupported Ruby implementation'
                              MriObject
                            end
     private_constant :ObjectImplementation
 
-    # TODO fix documentation
-    # @!macro [attach] synchronization_object
-    #
-    #   Safe synchronization under any Ruby implementation.
-    #   It provides methods like {#synchronize}, {#wait}, {#signal} and {#broadcast}.
-    #   Provides a single layer which can improve its implementation over time without changes needed to
-    #   the classes using it. Use {Synchronization::Object} not this abstract class.
-    #
-    #   @note this object does not support usage together with
-    #     [`Thread#wakeup`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-wakeup)
-    #     and [`Thread#raise`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-raise).
-    #     `Thread#sleep` and `Thread#wakeup` will work as expected but mixing `Synchronization::Object#wait` and
-    #     `Thread#wakeup` will not work on all platforms.
-    #
-    #   @see {Event} implementation as an example of this class use
-    #
-    #   @example simple
-    #     class AnClass < Synchronization::Object
-    #       def initialize
-    #         super
-    #         synchronize { @value = 'asd' }
-    #       end
-    #
-    #       def value
-    #         synchronize { @value }
-    #       end
-    #     end
-    #
+    # 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_volatile_with_cas}
     class Object < ObjectImplementation
 
+      # @!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 oly 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.
-      # Initializes default volatile fields with cas if any.
-      # @param [Array<Object>] defaults values for fields, in same order as they are defined
-      def initialize(*defaults)
-        super()
-        initialize_volatile_cas_fields(defaults)
+      def initialize
+        super
+        initialize_volatile_with_cas
       end
 
       # By calling this method on a class, it and all its children are marked to be constructed safely. Meaning that
@@ -62,7 +42,7 @@ module Concurrent
       #     safe_initialization!
       #
       #     def initialize
-      #       @AFinalValue = 'value' # published safly, does not have to be synchronized
+      #       @AFinalValue = 'value' # published safely, does not have to be synchronized
       #     end
       #   end
       def self.safe_initialization!
@@ -72,17 +52,20 @@ module Concurrent
         def self.new(*)
           object = super
         ensure
-          object.ensure_ivar_visibility! if object
+          object.full_memory_barrier if object
         end
 
         @safe_initialization = true
       end
 
+      # @return [true, false] if this class is safely initialized.
       def self.safe_initialization?
-        (defined?(@safe_initialization) && @safe_initialization) || (superclass.respond_to?(:safe_initialization?) && superclass.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.
+      # 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?}.
       def self.ensure_safe_initialization_when_final_fields_are_present
         Object.class_eval do
           def self.new(*)
@@ -96,14 +79,22 @@ module Concurrent
         end
       end
 
-      # TODO documentation
+      # 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.
       def self.attr_volatile_with_cas(*names)
         @volatile_cas_fields ||= []
         @volatile_cas_fields += names
         safe_initialization!
+        define_initialize_volatile_with_cas
 
         names.each do |name|
-          ivar = :"@VolatileCas_#{name}"
+          ivar = :"@VolatileCas#{name.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }}"
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}
               #{ivar}.get
@@ -126,11 +117,12 @@ module Concurrent
             end
           RUBY
         end
-        names.map { |n| [n, :"#{n}=", :"swap_#{n}", :"compare_and_set_#{n}"] }.flatten
+        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.volatile_cas_fields(inherited = true)
-        # TODO (pitr 11-Sep-2015): maybe use constant for better optimisation on Truffle since it will not speculate on ivar being final
         @volatile_cas_fields ||= []
         ((superclass.volatile_cas_fields if superclass.respond_to?(:volatile_cas_fields) && inherited) || []) +
             @volatile_cas_fields
@@ -138,18 +130,21 @@ module Concurrent
 
       private
 
-      def initialize_volatile_cas_fields(defaults)
-        self.class.volatile_cas_fields.zip(defaults) do |name, default|
-          instance_variable_set :"@VolatileCas_#{name}", AtomicReference.new(default)
-        end
-        nil
+      def self.define_initialize_volatile_with_cas
+        assignments = @volatile_cas_fields.map { |name| "@VolatileCas#{name.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }} = AtomicReference.new(nil)" }.join("\n")
+        class_eval <<-RUBY
+          def initialize_volatile_with_cas
+            super
+            #{assignments}
+          end
+        RUBY
       end
 
-      # @!method ensure_ivar_visibility!
-      #   @!macro synchronization_object_method_ensure_ivar_visibility
+      private_class_method :define_initialize_volatile_with_cas
+
+      def initialize_volatile_with_cas
+      end
 
-      # @!method self.attr_volatile(*names)
-      #   @!macro synchronization_object_method_self_attr_volatile
     end
   end
 end

data/lib/concurrent/synchronization/rbx_lockable_object.rb

@@ -18,15 +18,16 @@ module Concurrent
         if @__owner__ == Thread.current
           yield
         else
-          Rubinius.lock(self)
-          begin
-            @__owner__ = Thread.current
-            result = yield
-          ensure
-            @__owner__ = nil
-            Rubinius.unlock(self)
-            result
+          result = nil
+          Rubinius.synchronize(self) do
+            begin
+              @__owner__ = Thread.current
+              result     = yield
+            ensure
+              @__owner__ = nil
+            end
           end
+          result
         end
       end
 

data/lib/concurrent/synchronization/rbx_object.rb

@@ -1,37 +1,45 @@
 module Concurrent
   module Synchronization
 
+    module RbxAttrVolatile
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
 
-    # @!visibility private
-    # @!macro internal_implementation_note
-    class RbxObject < AbstractObject
-      def initialize
-        # nothing to do
+      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
         Rubinius.memory_barrier
       end
+    end
 
-      def self.attr_volatile *names
-        names.each do |name|
-          ivar = :"@volatile_#{name}"
-          class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}
-              Rubinius.memory_barrier
-              #{ivar}
-            end
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class RbxObject < AbstractObject
+      include RbxAttrVolatile
 
-            def #{name}=(value)
-              #{ivar} = value
-              Rubinius.memory_barrier
-            end
-          RUBY
-        end
-        names.map { |n| [n, :"#{n}="] }.flatten
+      def initialize
+        # nothing to do
       end
     end
-
   end
 end

data/lib/concurrent/synchronization/volatile.rb

@@ -0,0 +1,34 @@
+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? || Concurrent.on_truffle?
+      RbxAttrVolatile
+    else
+      MriAttrVolatile
+    end
+  end
+end

data/lib/concurrent/timer_task.rb

@@ -271,7 +271,6 @@ module Concurrent
     private
 
     def ns_initialize(opts, &task)
-      init_mutex(self)
       set_deref_options(opts)
 
       self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL

data/lib/concurrent/tvar.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'concurrent/synchronization'
 
 module Concurrent
 
@@ -8,7 +9,8 @@ module Concurrent
   # @!macro thread_safe_variable_comparison
   #
   # {include:file:doc/tvar.md}
-  class TVar
+  class TVar < Synchronization::Object
+    safe_initialization!
 
     # Create a new `TVar` with an initial value.
     def initialize(value)