Merge pull request #298 from ruby-concurrency/subclass-impl

Runtime-optimized Subclass Namespaces

Author: jdantonio

lib/concurrent/agent.rb

@@ -21,7 +21,18 @@ class Agent
     #
     # @param [Object] initial the initial value
     #
-    # @!macro executor_and_deref_options
+    # @!macro [attach] executor_and_deref_options
+    #  
+    #   @param [Hash] opts the options used to define the behavior at update and deref
+    #     and to specify the executor on which to perform actions
+    #   @option opts [Executor] :executor when set use the given `Executor` instance.
+    #     Three special values are also supported: `:task` returns the global task pool,
+    #     `:operation` returns the global operation pool, and `:immediate` returns a new
+    #     `ImmediateExecutor` object.
+    #   @option opts [Boolean] :dup_on_deref (false) call `#dup` before returning the data
+    #   @option opts [Boolean] :freeze_on_deref (false) call `#freeze` before returning the data
+    #   @option opts [Proc] :copy_on_deref (nil) call the given `Proc` passing
+    #     the internal value and returning the value returned from the proc
     def initialize(initial, opts = {})
       @value                = initial
       @rescuers             = []

lib/concurrent/atomic/atomic_boolean.rb

@@ -62,7 +62,7 @@ def true?
       synchronize { @value }
     end
 
-    # @!macro atomic_boolean_method_false_question
+    # @!macro [attach] atomic_boolean_method_false_question
     #
     #   Is the current value `false`
     #
@@ -91,57 +91,54 @@ def make_false
 
     protected
 
+    # @!visibility private
     def ns_initialize(initial)
       @value = !!initial
     end
 
+    # @!visibility private
     def ns_make_value(value)
       old = @value
       @value = value
       old != @value
     end
   end
 
-  if Concurrent.on_jruby?
-
-    class AtomicBoolean < JavaAtomicBoolean
-    end
-
-  elsif defined?(CAtomicBoolean)
-
-    # @!macro atomic_boolean
-    class CAtomicBoolean
-
-      # @!method initialize
-      #   @!macro atomic_boolean_method_initialize
-
-      # @!method value
-      #   @!macro atomic_boolean_method_value_get
-
-      # @!method value=
-      #   @!macro atomic_boolean_method_value_set
-
-      # @!method true?
-      #   @!macro atomic_boolean_method_true_question
-
-      # @!method false?
-      #   @!macro atomic_boolean_method_false_question
-
-      # @!method make_true
-      #   @!macro atomic_boolean_method_make_true
-
-      # @!method make_false
-      #   @!macro atomic_boolean_method_make_false
-    end
-
-    # @!macro atomic_boolean
-    class AtomicBoolean < CAtomicBoolean
-    end
-
-  else
-
-    # @!macro atomic_boolean
-    class AtomicBoolean < MutexAtomicBoolean
-    end
+  AtomicBooleanImplementation = case
+                                when Concurrent.on_jruby?
+                                  JavaAtomicBoolean
+                                when defined?(CAtomicBoolean)
+                                  CAtomicBoolean
+                                else
+                                  MutexAtomicBoolean
+                                end
+  private_constant :AtomicBooleanImplementation
+
+  # @!macro atomic_boolean
+  #
+  # @see Concurrent::MutexAtomicBoolean
+  class AtomicBoolean < AtomicBooleanImplementation
+    
+    # @!method initialize(initial = false)
+    #   @!macro atomic_boolean_method_initialize
+    
+    # @!method value
+    #   @!macro atomic_boolean_method_value_get
+    
+    # @!method value=(value)
+    #   @!macro atomic_boolean_method_value_set
+    
+    # @!method true?
+    #   @!macro atomic_boolean_method_true_question
+    
+    # @!method false?
+    #   @!macro atomic_boolean_method_false_question
+    
+    # @!method make_true
+    #   @!macro atomic_boolean_method_make_true
+    
+    # @!method make_false
+    #   @!macro atomic_boolean_method_make_false
+    
   end
 end

lib/concurrent/atomic/atomic_fixnum.rb

@@ -90,7 +90,7 @@ def decrement
     #   @param [Fixnum] expect the expected value
     #   @param [Fixnum] update the new value
     #
-    #   @return [Boolean] true if the value was updated else false
+    #   @return [Fixnum] true if the value was updated else false
     def compare_and_set(expect, update)
       synchronize do
         if @value == expect
@@ -104,17 +104,20 @@ def compare_and_set(expect, update)
 
     protected
 
+    # @!visibility private
     def ns_initialize(initial)
       ns_set(initial)
     end
 
     private
 
+    # @!visibility private
     def ns_set(value)
       range_check!(value)
       @value = value
     end
 
+    # @!visibility private
     def range_check!(value)
       if !value.is_a?(Fixnum)
         raise ArgumentError.new('value value must be a Fixnum')
@@ -128,44 +131,38 @@ def range_check!(value)
     end
   end
 
-  if Concurrent.on_jruby?
-
-    # @!macro atomic_fixnum
-    class AtomicFixnum < JavaAtomicFixnum
-    end
-
-  elsif defined?(CAtomicFixnum)
-
-    # @!macro atomic_fixnum
-    class CAtomicFixnum
-
-      # @!method initialize
-      #   @!macro atomic_fixnum_method_initialize
-
-      # @!method value
-      #   @!macro atomic_fixnum_method_value_get
+  AtomicFixnumImplementation = case
+                               when Concurrent.on_jruby?
+                                 JavaAtomicFixnum
+                               when defined?(CAtomicFixnum)
+                                 CAtomicFixnum
+                               else
+                                 MutexAtomicFixnum
+                               end
+  private_constant :AtomicFixnumImplementation
+
+  # @!macro atomic_fixnum
+  #
+  # @see Concurrent::MutexAtomicFixnum
+  class AtomicFixnum < AtomicFixnumImplementation
+    
+    # @!method initialize(initial = 0)
+    #   @!macro atomic_fixnum_method_initialize
 
-      # @!method value=
-      #   @!macro atomic_fixnum_method_value_set
+    # @!method value
+    #   @!macro atomic_fixnum_method_value_get
 
-      # @!method increment
-      #   @!macro atomic_fixnum_method_increment
+    # @!method value=(value)
+    #   @!macro atomic_fixnum_method_value_set
 
-      # @!method decrement
-      #   @!macro atomic_fixnum_method_decrement
+    # @!method increment
+    #   @!macro atomic_fixnum_method_increment
 
-      # @!method compare_and_set
-      #   @!macro atomic_fixnum_method_compare_and_set
-    end
+    # @!method decrement
+    #   @!macro atomic_fixnum_method_decrement
 
-    # @!macro atomic_fixnum
-    class AtomicFixnum < CAtomicFixnum
-    end
+    # @!method compare_and_set(expect, update)
+    #   @!macro atomic_fixnum_method_compare_and_set
 
-  else
-
-    # @!macro atomic_fixnum
-    class AtomicFixnum < MutexAtomicFixnum
-    end
   end
 end

lib/concurrent/atomic/semaphore.rb

@@ -1,7 +1,17 @@
 require 'concurrent/synchronization'
 
 module Concurrent
+
+  # @!macro [attach] semaphore
+  #
+  #   A counting semaphore. Conceptually, a semaphore maintains a set of
+  #   permits. Each {#acquire} blocks if necessary until a permit is
+  #   available, and then takes it. Each {#release} adds a permit, potentially
+  #   releasing a blocking acquirer.
+  #   However, no actual permit objects are used; the Semaphore just keeps a
+  #   count of the number available and acts accordingly.
   class MutexSemaphore < Synchronization::Object
+
     # @!macro [attach] semaphore_method_initialize
     #
     #   Create a new `Semaphore` with the initial `count`.
@@ -129,12 +139,14 @@ def reduce_permits(reduction)
 
     protected
 
+    # @!visibility private
     def ns_initialize(count)
       @free = count
     end
 
     private
 
+    # @!visibility private
     def try_acquire_now(permits)
       if @free >= permits
         @free -= permits
@@ -144,28 +156,45 @@ def try_acquire_now(permits)
       end
     end
 
+    # @!visibility private
     def try_acquire_timed(permits, timeout)
       ns_wait_until(timeout) { try_acquire_now(permits) }
     end
   end
 
-  if Concurrent.on_jruby?
+  SemaphoreImplementation = case
+                            when Concurrent.on_jruby?
+                              JavaSemaphore
+                            else
+                              MutexSemaphore
+                            end
+  private_constant :SemaphoreImplementation
 
-    # @!macro semaphore
-    #
-    #   A counting semaphore. Conceptually, a semaphore maintains a set of
-    #   permits. Each {#acquire} blocks if necessary until a permit is
-    #   available, and then takes it. Each {#release} adds a permit, potentially
-    #   releasing a blocking acquirer.
-    #   However, no actual permit objects are used; the Semaphore just keeps a
-    #   count of the number available and acts accordingly.
-    class Semaphore < JavaSemaphore
-    end
+  # @!macro semaphore
+  #
+  # @see Concurrent::MutexSemaphore
+  class Semaphore < SemaphoreImplementation
 
-  else
+    # @!method initialize(count)
+    #   @!macro semaphore_method_initialize
+
+    # @!method acquire(permits = 1)
+    #   @!macro semaphore_method_acquire
+
+    # @!method available_permits
+    #   @!macro semaphore_method_available_permits
+
+    # @!method drain_permits
+    #   @!macro semaphore_method_drain_permits
+
+    # @!method try_acquire(permits = 1, timeout = nil)
+    #   @!macro semaphore_method_try_acquire
+
+    # @!method release(permits = 1)
+    #   @!macro semaphore_method_release
+
+    # @!method reduce_permits(reduction)
+    #   @!macro semaphore_method_reduce_permits
 
-    # @!macro semaphore
-    class Semaphore < MutexSemaphore
-    end
   end
 end