thread_safe 0.0.3 → 0.1.0

data/lib/thread_safe/cache.rb

@@ -0,0 +1,137 @@
+require 'thread'
+
+module ThreadSafe
+  autoload :JRubyCacheBackend,           'thread_safe/jruby_cache_backend'
+  autoload :MriCacheBackend,             'thread_safe/mri_cache_backend'
+  autoload :NonConcurrentCacheBackend,   'thread_safe/non_concurrent_cache_backend'
+  autoload :AtomicReferenceCacheBackend, 'thread_safe/atomic_reference_cache_backend'
+  autoload :SynchronizedCacheBackend,    'thread_safe/synchronized_cache_backend'
+
+  ConcurrentCacheBackend =
+    case defined?(RUBY_ENGINE) && RUBY_ENGINE
+    when 'jruby'; JRubyCacheBackend
+    when 'ruby';  MriCacheBackend
+    when 'rbx';   AtomicReferenceCacheBackend
+    else
+      warn 'ThreadSafe: unsupported Ruby engine, using a fully synchronized ThreadSafe::Cache implementation' if $VERBOSE
+      SynchronizedCacheBackend
+    end
+
+  class Cache < ConcurrentCacheBackend
+    KEY_ERROR = defined?(KeyError) ? KeyError : IndexError # there is no KeyError in 1.8 mode
+
+    def initialize(options = nil, &block)
+      if options.kind_of?(::Hash)
+        validate_options_hash!(options)
+      else
+        options = nil
+      end
+
+      super(options)
+      @default_proc = block
+    end
+
+    def [](key)
+      if value = super
+        value
+      elsif @default_proc && !key?(key)
+        @default_proc.call(self, key)
+      else
+        value
+      end
+    end
+
+    def fetch(key, default_value = NULL)
+      if NULL != (value = get_or_default(key, NULL))
+        value
+      elsif block_given?
+        yield key
+      elsif NULL != default_value
+        default_value
+      else
+        raise KEY_ERROR, 'key not found'
+      end
+    end
+
+    def put_if_absent(key, value)
+      computed = false
+      result = compute_if_absent(key) do
+        computed = true
+        value
+      end
+      computed ? nil : result
+    end unless method_defined?(:put_if_absent)
+
+    def value?(value)
+      each_value do |v|
+        return true if value.equal?(v)
+      end
+      false
+    end unless method_defined?(:value?)
+
+    def keys
+      arr = []
+      each_pair {|k, v| arr << k}
+      arr
+    end unless method_defined?(:keys)
+
+    def values
+      arr = []
+      each_pair {|k, v| arr << v}
+      arr
+    end unless method_defined?(:values)
+
+    def each_key
+      each_pair {|k, v| yield k}
+    end unless method_defined?(:each_key)
+
+    def each_value
+      each_pair {|k, v| yield v}
+    end unless method_defined?(:each_value)
+
+    def empty?
+      each_pair {|k, v| return false}
+      true
+    end unless method_defined?(:empty?)
+
+    def size
+      count = 0
+      each_pair {|k, v| count += 1}
+      count
+    end unless method_defined?(:size)
+
+    def marshal_dump
+      raise TypeError, "can't dump hash with default proc" if @default_proc
+      h = {}
+      each_pair {|k, v| h[k] = v}
+      h
+    end
+
+    def marshal_load(hash)
+      initialize
+      populate_from(hash)
+    end
+
+    undef :freeze
+
+    private
+    def initialize_copy(other)
+      super
+      populate_from(other)
+    end
+
+    def populate_from(hash)
+      hash.each_pair {|k, v| self[k] = v}
+      self
+    end
+
+    def validate_options_hash!(options)
+      if (initial_capacity = options[:initial_capacity]) && (!initial_capacity.kind_of?(Fixnum) || initial_capacity < 0)
+        raise ArgumentError, ":initial_capacity must be a positive Fixnum"
+      end
+      if (load_factor = options[:load_factor]) && (!load_factor.kind_of?(Numeric) || load_factor <= 0 || load_factor > 1)
+        raise ArgumentError, ":load_factor must be a number between 0 and 1"
+      end
+    end
+  end
+end

data/lib/thread_safe/mri_cache_backend.rb

@@ -0,0 +1,62 @@
+module ThreadSafe
+  class MriCacheBackend < NonConcurrentCacheBackend
+    # We can get away with a single global write lock (instead of a per-instance one) because of the GVL/green threads.
+    #
+    # The previous implementation used `Thread.critical` on 1.8 MRI to implement the 4 composed atomic operations (`put_if_absent`, `replace_pair`,
+    # `replace_if_exists`, `delete_pair`) this however doesn't work for `compute_if_absent` because on 1.8 the Mutex class is itself implemented
+    # via `Thread.critical` and a call to `Mutex#lock` does not restore the previous `Thread.critical` value (thus any synchronisation clears the 
+    # `Thread.critical` flag and we loose control). This poses a problem as the provided block might use synchronisation on its own.
+    #
+    # NOTE: a neat idea of writing a c-ext to manually perform atomic put_if_absent, while relying on Ruby not releasing a GVL while calling
+    # a c-ext will not work because of the potentially Ruby implemented `#hash` and `#eql?` key methods.
+    WRITE_LOCK = Mutex.new
+
+    def []=(key, value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def compute_if_absent(key)
+      if stored_value = _get(key) # fast non-blocking path for the most likely case
+        stored_value
+      else
+        WRITE_LOCK.synchronize { super }
+      end
+    end
+
+    def compute_if_present(key)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def compute(key)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def merge_pair(key, value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def replace_pair(key, old_value, new_value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def replace_if_exists(key, new_value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def get_and_set(key, value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def delete(key)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def delete_pair(key, value)
+      WRITE_LOCK.synchronize { super }
+    end
+
+    def clear
+      WRITE_LOCK.synchronize { super }
+    end
+  end
+end

data/lib/thread_safe/non_concurrent_cache_backend.rb

@@ -0,0 +1,133 @@
+module ThreadSafe
+  class NonConcurrentCacheBackend
+    # WARNING: all public methods of the class must operate on the @backend directly without calling each other. This is important
+    # because of the SynchronizedCacheBackend which uses a non-reentrant mutex for perfomance reasons.
+    def initialize(options = nil)
+      @backend = {}
+    end
+
+    def [](key)
+      @backend[key]
+    end
+
+    def []=(key, value)
+      @backend[key] = value
+    end
+
+    def compute_if_absent(key)
+      if NULL != (stored_value = @backend.fetch(key, NULL))
+        stored_value
+      else
+        @backend[key] = yield
+      end
+    end
+
+    def replace_pair(key, old_value, new_value)
+      if pair?(key, old_value)
+        @backend[key] = new_value
+        true
+      else
+        false
+      end
+    end
+
+    def replace_if_exists(key, new_value)
+      if NULL != (stored_value = @backend.fetch(key, NULL))
+        @backend[key] = new_value
+        stored_value
+      end
+    end
+
+    def compute_if_present(key)
+      if NULL != (stored_value = @backend.fetch(key, NULL))
+        store_computed_value(key, yield(stored_value))
+      end
+    end
+
+    def compute(key)
+      store_computed_value(key, yield(@backend[key]))
+    end
+
+    def merge_pair(key, value)
+      if NULL == (stored_value = @backend.fetch(key, NULL))
+        @backend[key] = value
+      else
+        store_computed_value(key, yield(stored_value))
+      end
+    end
+
+    def get_and_set(key, value)
+      stored_value = @backend[key]
+      @backend[key] = value
+      stored_value
+    end
+
+    def key?(key)
+      @backend.key?(key)
+    end
+
+    def value?(value)
+      @backend.value?(value)
+    end
+
+    def delete(key)
+      @backend.delete(key)
+    end
+
+    def delete_pair(key, value)
+      if pair?(key, value)
+        @backend.delete(key)
+        true
+      else
+        false
+      end
+    end
+
+    def clear
+      @backend.clear
+      self
+    end
+
+    def each_pair
+      dupped_backend.each_pair do |k, v|
+        yield k, v
+      end
+      self
+    end
+
+    def size
+      @backend.size
+    end
+
+    def get_or_default(key, default_value)
+      @backend.fetch(key, default_value)
+    end
+
+    alias_method :_get, :[]
+    alias_method :_set, :[]=
+    private :_get, :_set
+    private
+    def initialize_copy(other)
+      super
+      @backend = {}
+      self
+    end
+
+    def dupped_backend
+      @backend.dup
+    end
+
+    def pair?(key, expected_value)
+      NULL != (stored_value = @backend.fetch(key, NULL)) && expected_value.equal?(stored_value)
+    end
+
+    def store_computed_value(key, new_value)
+      if new_value.nil?
+        @backend.delete(key)
+        nil
+      else
+        @backend[key] = new_value
+      end
+    end
+  end
+end

data/lib/thread_safe/synchronized_cache_backend.rb

@@ -0,0 +1,76 @@
+module ThreadSafe
+  class SynchronizedCacheBackend < NonConcurrentCacheBackend
+    require 'mutex_m'
+    include Mutex_m
+    # WARNING: Mutex_m is a non-reentrant lock, so the synchronized methods are not allowed to call each other.
+
+    def [](key)
+      synchronize { super }
+    end
+
+    def []=(key, value)
+      synchronize { super }
+    end
+
+    def compute_if_absent(key)
+      synchronize { super }
+    end
+
+    def compute_if_present(key)
+      synchronize { super }
+    end
+
+    def compute(key)
+      synchronize { super }
+    end
+
+    def merge_pair(key, value)
+      synchronize { super }
+    end
+
+    def replace_pair(key, old_value, new_value)
+      synchronize { super }
+    end
+
+    def replace_if_exists(key, new_value)
+      synchronize { super }
+    end
+
+    def get_and_set(key, value)
+      synchronize { super }
+    end
+
+    def key?(key)
+      synchronize { super }
+    end
+
+    def value?(value)
+      synchronize { super }
+    end
+
+    def delete(key)
+      synchronize { super }
+    end
+
+    def delete_pair(key, value)
+      synchronize { super }
+    end
+
+    def clear
+      synchronize { super }
+    end
+
+    def size
+      synchronize { super }
+    end
+
+    def get_or_default(key, default_value)
+      synchronize { super }
+    end
+
+    private
+    def dupped_backend
+      synchronize { super }
+    end
+  end
+end

data/lib/thread_safe/util.rb

@@ -0,0 +1,16 @@
+module ThreadSafe
+  module Util
+    FIXNUM_BIT_SIZE = (0.size * 8) - 2
+    MAX_INT         = (2 ** FIXNUM_BIT_SIZE) - 1
+    CPU_COUNT       = 16 # is there a way to determine this?
+
+    autoload :AtomicReference, 'thread_safe/util/atomic_reference'
+    autoload :Adder,           'thread_safe/util/adder'
+    autoload :CheapLockable,   'thread_safe/util/cheap_lockable'
+    autoload :PowerOfTwoTuple, 'thread_safe/util/power_of_two_tuple'
+    autoload :Striped64,       'thread_safe/util/striped64'
+    autoload :Volatile,        'thread_safe/util/volatile'
+    autoload :VolatileTuple,   'thread_safe/util/volatile_tuple'
+    autoload :XorShiftRandom,  'thread_safe/util/xor_shift_random'
+  end
+end

data/lib/thread_safe/util/adder.rb

@@ -0,0 +1,59 @@
+module ThreadSafe
+  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.
+    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