concurrent-ruby 1.1.5

data/lib/concurrent/atomic/ruby_thread_local_var.rb

@@ -0,0 +1,161 @@
+require 'thread'
+require 'concurrent/atomic/abstract_thread_local_var'
+
+module Concurrent
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  class RubyThreadLocalVar < AbstractThreadLocalVar
+
+    # Each thread has a (lazily initialized) array of thread-local variable values
+    # Each time a new thread-local var is created, we allocate an "index" for it
+    # For example, if the allocated index is 1, that means slot #1 in EVERY
+    #   thread's thread-local array will be used for the value of that TLV
+    #
+    # The good thing about using a per-THREAD structure to hold values, rather
+    #   than a per-TLV structure, is that no synchronization is needed when
+    #    reading and writing those values (since the structure is only ever
+    #    accessed by a single thread)
+    #
+    # Of course, when a TLV is GC'd, 1) we need to recover its index for use
+    #   by other new TLVs (otherwise the thread-local arrays could get bigger
+    #   and bigger with time), and 2) we need to null out all the references
+    #   held in the now-unused slots (both to avoid blocking GC of those objects,
+    #   and also to prevent "stale" values from being passed on to a new TLV
+    #   when the index is reused)
+    # Because we need to null out freed slots, we need to keep references to
+    #   ALL the thread-local arrays -- ARRAYS is for that
+    # But when a Thread is GC'd, we need to drop the reference to its thread-local
+    #   array, so we don't leak memory
+
+    # @!visibility private
+    FREE   = []
+    LOCK   = Mutex.new
+    ARRAYS = {} # used as a hash set
+    @@next = 0
+    private_constant :FREE, :LOCK, :ARRAYS
+
+    # @!macro thread_local_var_method_get
+    def value
+      if array = get_threadlocal_array
+        value = array[@index]
+        if value.nil?
+          default
+        elsif value.equal?(NULL)
+          nil
+        else
+          value
+        end
+      else
+        default
+      end
+    end
+
+    # @!macro thread_local_var_method_set
+    def value=(value)
+      me = Thread.current
+      # We could keep the thread-local arrays in a hash, keyed by Thread
+      # But why? That would require locking
+      # Using Ruby's built-in thread-local storage is faster
+      unless array = get_threadlocal_array(me)
+        array = set_threadlocal_array([], me)
+        LOCK.synchronize { ARRAYS[array.object_id] = array }
+        ObjectSpace.define_finalizer(me, self.class.thread_finalizer(array))
+      end
+      array[@index] = (value.nil? ? NULL : value)
+      value
+    end
+
+    protected
+
+    # @!visibility private
+    def allocate_storage
+      @index = LOCK.synchronize do
+        FREE.pop || begin
+          result = @@next
+          @@next += 1
+          result
+        end
+      end
+      ObjectSpace.define_finalizer(self, self.class.threadlocal_finalizer(@index))
+    end
+
+    # @!visibility private
+    def self.threadlocal_finalizer(index)
+      proc do
+        Thread.new do # avoid error: can't be called from trap context
+          LOCK.synchronize do
+            FREE.push(index)
+            # The cost of GC'ing a TLV is linear in the number of threads using TLVs
+            # But that is natural! More threads means more storage is used per TLV
+            # So naturally more CPU time is required to free more storage
+            ARRAYS.each_value do |array|
+              array[index] = nil
+            end
+          end
+        end
+      end
+    end
+
+    # @!visibility private
+    def self.thread_finalizer(array)
+      proc do
+        Thread.new do # avoid error: can't be called from trap context
+          LOCK.synchronize do
+            # The thread which used this thread-local array is now gone
+            # So don't hold onto a reference to the array (thus blocking GC)
+            ARRAYS.delete(array.object_id)
+          end
+        end
+      end
+    end
+
+    private
+
+    if Thread.instance_methods.include?(:thread_variable_get)
+
+      def get_threadlocal_array(thread = Thread.current)
+        thread.thread_variable_get(:__threadlocal_array__)
+      end
+
+      def set_threadlocal_array(array, thread = Thread.current)
+        thread.thread_variable_set(:__threadlocal_array__, array)
+      end
+
+    else
+
+      def get_threadlocal_array(thread = Thread.current)
+        thread[:__threadlocal_array__]
+      end
+
+      def set_threadlocal_array(array, thread = Thread.current)
+        thread[:__threadlocal_array__] = array
+      end
+    end
+
+    # This exists only for use in testing
+    # @!visibility private
+    def value_for(thread)
+      if array = get_threadlocal_array(thread)
+        value = array[@index]
+        if value.nil?
+          default_for(thread)
+        elsif value.equal?(NULL)
+          nil
+        else
+          value
+        end
+      else
+        default_for(thread)
+      end
+    end
+
+    def default_for(thread)
+      if @default_block
+        raise "Cannot use default_for with default block"
+      else
+        @default
+      end
+    end
+  end
+end

data/lib/concurrent/atomic/semaphore.rb

@@ -0,0 +1,145 @@
+require 'concurrent/atomic/mutex_semaphore'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  ###################################################################
+
+  # @!macro semaphore_method_initialize
+  #
+  #   Create a new `Semaphore` with the initial `count`.
+  #
+  #   @param [Fixnum] count the initial count
+  #
+  #   @raise [ArgumentError] if `count` is not an integer or is less than zero
+
+  # @!macro semaphore_method_acquire
+  #
+  #   Acquires the given number of permits from this semaphore,
+  #     blocking until all are available.
+  #
+  #   @param [Fixnum] permits Number of permits to acquire
+  #
+  #   @raise [ArgumentError] if `permits` is not an integer or is less than
+  #     one
+  #
+  #   @return [nil]
+
+  # @!macro semaphore_method_available_permits
+  #
+  #   Returns the current number of permits available in this semaphore.
+  #
+  #   @return [Integer]
+
+  # @!macro semaphore_method_drain_permits
+  #
+  #   Acquires and returns all permits that are immediately available.
+  #
+  #   @return [Integer]
+
+  # @!macro semaphore_method_try_acquire
+  #
+  #   Acquires the given number of permits from this semaphore,
+  #     only if all are available at the time of invocation or within
+  #     `timeout` interval
+  #
+  #   @param [Fixnum] permits the number of permits to acquire
+  #
+  #   @param [Fixnum] timeout the number of seconds to wait for the counter
+  #     or `nil` to return immediately
+  #
+  #   @raise [ArgumentError] if `permits` is not an integer or is less than
+  #     one
+  #
+  #   @return [Boolean] `false` if no permits are available, `true` when
+  #     acquired a permit
+
+  # @!macro semaphore_method_release
+  #
+  #   Releases the given number of permits, returning them to the semaphore.
+  #
+  #   @param [Fixnum] permits Number of permits to return to the semaphore.
+  #
+  #   @raise [ArgumentError] if `permits` is not a number or is less than one
+  #
+  #   @return [nil]
+
+  ###################################################################
+
+  # @!macro semaphore_public_api
+  #
+  #   @!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
+
+  ###################################################################
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  SemaphoreImplementation = case
+                            when defined?(JavaSemaphore)
+                              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.
+  #
+  # @!macro semaphore_public_api
+  # @example
+  #   semaphore = Concurrent::Semaphore.new(2)
+  #
+  #   t1 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 1 acquired semaphore"
+  #   end
+  #
+  #   t2 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 2 acquired semaphore"
+  #   end
+  #
+  #   t3 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 3 acquired semaphore"
+  #   end
+  #
+  #   t4 = Thread.new do
+  #     sleep(2)
+  #     puts "Thread 4 releasing semaphore"
+  #     semaphore.release
+  #   end
+  #
+  #   [t1, t2, t3, t4].each(&:join)
+  #
+  #   # prints:
+  #   # Thread 3 acquired semaphore
+  #   # Thread 2 acquired semaphore
+  #   # Thread 4 releasing semaphore
+  #   # Thread 1 acquired semaphore
+  #
+  class Semaphore < SemaphoreImplementation
+  end
+end

data/lib/concurrent/atomic/thread_local_var.rb

@@ -0,0 +1,104 @@
+require 'concurrent/atomic/ruby_thread_local_var'
+require 'concurrent/atomic/java_thread_local_var'
+require 'concurrent/utility/engine'
+
+module Concurrent
+
+  ###################################################################
+
+  # @!macro thread_local_var_method_initialize
+  #
+  #   Creates a thread local variable.
+  #
+  #   @param [Object] default the default value when otherwise unset
+  #   @param [Proc] default_block Optional block that gets called to obtain the
+  #     default value for each thread
+
+  # @!macro thread_local_var_method_get
+  #
+  #   Returns the value in the current thread's copy of this thread-local variable.
+  #
+  #   @return [Object] the current value
+
+  # @!macro thread_local_var_method_set
+  #
+  #   Sets the current thread's copy of this thread-local variable to the specified value.
+  #
+  #   @param [Object] value the value to set
+  #   @return [Object] the new value
+
+  # @!macro thread_local_var_method_bind
+  #
+  #   Bind the given value to thread local storage during
+  #   execution of the given block.
+  #
+  #   @param [Object] value the value to bind
+  #   @yield the operation to be performed with the bound variable
+  #   @return [Object] the value
+
+
+  ###################################################################
+
+  # @!macro thread_local_var_public_api
+  #
+  #   @!method initialize(default = nil, &default_block)
+  #     @!macro thread_local_var_method_initialize
+  #
+  #   @!method value
+  #     @!macro thread_local_var_method_get
+  #
+  #   @!method value=(value)
+  #     @!macro thread_local_var_method_set
+  #
+  #   @!method bind(value, &block)
+  #     @!macro thread_local_var_method_bind
+
+  ###################################################################
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  ThreadLocalVarImplementation = case
+                                 when Concurrent.on_jruby?
+                                   JavaThreadLocalVar
+                                 else
+                                   RubyThreadLocalVar
+                                 end
+  private_constant :ThreadLocalVarImplementation
+
+  # @!macro thread_local_var
+  #
+  #   A `ThreadLocalVar` is a variable where the value is different for each thread.
+  #   Each variable may have a default value, but when you modify the variable only
+  #   the current thread will ever see that change.
+  #
+  #   @!macro thread_safe_variable_comparison
+  #
+  #   @example
+  #     v = ThreadLocalVar.new(14)
+  #     v.value #=> 14
+  #     v.value = 2
+  #     v.value #=> 2
+  #
+  #   @example
+  #     v = ThreadLocalVar.new(14)
+  #
+  #     t1 = Thread.new do
+  #       v.value #=> 14
+  #       v.value = 1
+  #       v.value #=> 1
+  #     end
+  #
+  #     t2 = Thread.new do
+  #       v.value #=> 14
+  #       v.value = 2
+  #       v.value #=> 2
+  #     end
+  #
+  #     v.value #=> 14
+  #
+  #   @see https://docs.oracle.com/javase/7/docs/api/java/lang/ThreadLocal.html Java ThreadLocal
+  #
+  # @!macro thread_local_var_public_api
+  class ThreadLocalVar < ThreadLocalVarImplementation
+  end
+end

data/lib/concurrent/atomic_reference/mutex_atomic.rb

@@ -0,0 +1,56 @@
+module Concurrent
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  class MutexAtomicReference < Synchronization::LockableObject
+    include AtomicDirectUpdate
+    include AtomicNumericCompareAndSetWrapper
+    alias_method :compare_and_swap, :compare_and_set
+
+    # @!macro atomic_reference_method_initialize
+    def initialize(value = nil)
+      super()
+      synchronize { ns_initialize(value) }
+    end
+
+    # @!macro atomic_reference_method_get
+    def get
+      synchronize { @value }
+    end
+    alias_method :value, :get
+
+    # @!macro atomic_reference_method_set
+    def set(new_value)
+      synchronize { @value = new_value }
+    end
+    alias_method :value=, :set
+
+    # @!macro atomic_reference_method_get_and_set
+    def get_and_set(new_value)
+      synchronize do
+        old_value = @value
+        @value = new_value
+        old_value
+      end
+    end
+    alias_method :swap, :get_and_set
+
+    # @!macro atomic_reference_method_compare_and_set
+    def _compare_and_set(old_value, new_value)
+      synchronize do
+        if @value.equal? old_value
+          @value = new_value
+          true
+        else
+          false
+        end
+      end
+    end
+
+    protected
+
+    def ns_initialize(value)
+      @value = value
+    end
+  end
+end