thread_safe 0.0.3 → 0.1.0

data/lib/thread_safe/util/atomic_reference.rb

@@ -0,0 +1,12 @@
+module ThreadSafe
+  module Util
+    # An overhead-less atomic reference.
+    AtomicReference =
+      if defined?(Rubinius::AtomicReference)
+        Rubinius::AtomicReference
+      else
+        require 'atomic'
+        defined?(Atomic::InternalReference) ? Atomic::InternalReference : Atomic
+      end
+  end
+end

data/lib/thread_safe/util/cheap_lockable.rb

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

data/lib/thread_safe/util/power_of_two_tuple.rb

@@ -0,0 +1,26 @@
+module ThreadSafe
+  module Util
+    class PowerOfTwoTuple < VolatileTuple
+      def initialize(size)
+        raise ArgumentError, "size must be a power of 2 (#{size.inspect} provided)" unless size > 0 && size & (size - 1) == 0
+        super(size)
+      end
+
+      def hash_to_index(hash)
+        (size - 1) & hash
+      end
+
+      def volatile_get_by_hash(hash)
+        volatile_get(hash_to_index(hash))
+      end
+
+      def volatile_set_by_hash(hash, value)
+        volatile_set(hash_to_index(hash), value)
+      end
+
+      def next_in_size_table
+        self.class.new(size << 1)
+      end
+    end
+  end
+end

data/lib/thread_safe/util/striped64.rb

@@ -0,0 +1,226 @@
+module ThreadSafe
+  module Util
+    # A Ruby port of the Doug Lea's jsr166e.Striped64 class version 1.6 available in public domain.
+    # Original source code available here: http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/jsr166e/Striped64.java?revision=1.6
+    #
+    # Class holding common representation and mechanics for classes supporting dynamic striping on 64bit values.
+    #
+    # This class maintains a lazily-initialized table of atomically
+    # updated variables, plus an extra +base+ field. The table size
+    # is a power of two. Indexing uses masked per-thread hash codes.
+    # Nearly all methods on this class are private, accessed directly
+    # by subclasses.
+    #
+    # Table entries are of class +Cell+; a variant of AtomicLong padded
+    # to reduce cache contention on most processors. Padding is
+    # overkill for most Atomics because they are usually irregularly
+    # scattered in memory and thus don't interfere much with each
+    # other. But Atomic objects residing in arrays will tend to be
+    # placed adjacent to each other, and so will most often share
+    # cache lines (with a huge negative performance impact) without
+    # this precaution.
+    #
+    # In part because +Cell+s are relatively large, we avoid creating
+    # them until they are needed.  When there is no contention, all
+    # updates are made to the +base+ field.  Upon first contention (a
+    # failed CAS on +base+ update), the table is initialized to size 2.
+    # The table size is doubled upon further contention until
+    # reaching the nearest power of two greater than or equal to the
+    # number of CPUS. Table slots remain empty (+nil+) until they are
+    # needed.
+    #
+    # A single spinlock (+busy+) is used for initializing and
+    # resizing the table, as well as populating slots with new +Cell+s.
+    # There is no need for a blocking lock: When the lock is not
+    # available, threads try other slots (or the base).  During these
+    # retries, there is increased contention and reduced locality,
+    # which is still better than alternatives.
+    #
+    # Per-thread hash codes are initialized to random values.
+    # Contention and/or table collisions are indicated by failed
+    # CASes when performing an update operation (see method
+    # +retry_update+). Upon a collision, if the table size is less than
+    # the capacity, it is doubled in size unless some other thread
+    # holds the lock. If a hashed slot is empty, and lock is
+    # available, a new +Cell+ is created. Otherwise, if the slot
+    # exists, a CAS is tried.  Retries proceed by "double hashing",
+    # using a secondary hash (XorShift) to try to find a
+    # free slot.
+    #
+    # The table size is capped because, when there are more threads
+    # than CPUs, supposing that each thread were bound to a CPU,
+    # there would exist a perfect hash function mapping threads to
+    # slots that eliminates collisions. When we reach capacity, we
+    # search for this mapping by randomly varying the hash codes of
+    # colliding threads.  Because search is random, and collisions
+    # only become known via CAS failures, convergence can be slow,
+    # and because threads are typically not bound to CPUS forever,
+    # may not occur at all. However, despite these limitations,
+    # observed contention rates are typically low in these cases.
+    #
+    # It is possible for a +Cell+ to become unused when threads that
+    # once hashed to it terminate, as well as in the case where
+    # doubling the table causes no thread to hash to it under
+    # expanded mask.  We do not try to detect or remove such cells,
+    # under the assumption that for long-running instances, observed
+    # contention levels will recur, so the cells will eventually be
+    # needed again; and for short-lived ones, it does not matter.
+    class Striped64
+      # Padded variant of AtomicLong supporting only raw accesses plus CAS.
+      # The +value+ field is placed between pads, hoping that the JVM doesn't
+      # reorder them.
+      #
+      # Optimisation note: It would be possible to use a release-only
+      # form of CAS here, if it were provided.
+      class Cell < AtomicReference
+        # TODO: this only adds padding after the :value slot, need to find a way to add padding before the slot
+        attr_reader *(Array.new(12).map {|i| :"padding_#{i}"})
+
+        alias_method :cas, :compare_and_set
+
+        def cas_computed
+          cas(current_value = value, yield(current_value))
+        end
+      end
+
+      extend Volatile
+      attr_volatile :cells, # Table of cells. When non-null, size is a power of 2.
+                    :base,  # Base value, used mainly when there is no contention, but also as a fallback during table initialization races. Updated via CAS.
+                    :busy   # Spinlock (locked via CAS) used when resizing and/or creating Cells.
+
+      alias_method :busy?, :busy
+
+      def initialize
+        super()
+        self.busy = false
+        self.base = 0
+      end
+
+      # Handles cases of updates involving initialization, resizing,
+      # creating new Cells, and/or contention. See above for
+      # explanation. This method suffers the usual non-modularity
+      # problems of optimistic retry code, relying on rechecked sets of
+      # reads.
+      #
+      # Arguments:
+      # [+x+]
+      #   the value
+      # [+hash_code+]
+      #   hash code used
+      # [+x+]
+      #   false if CAS failed before call
+      def retry_update(x, hash_code, was_uncontended) # :yields: current_value
+        hash     = hash_code
+        collided = false # True if last slot nonempty
+        while true
+          if current_cells = cells
+            if !(cell = current_cells.volatile_get_by_hash(hash))
+              if busy?
+                collided = false
+              else # Try to attach new Cell
+                if try_to_install_new_cell(Cell.new(x), hash) # Optimistically create and try to insert new cell
+                  break
+                else
+                  redo # Slot is now non-empty
+                end
+              end
+            elsif !was_uncontended # CAS already known to fail
+              was_uncontended = true # Continue after rehash
+            elsif cell.cas_computed {|current_value| yield current_value}
+              break
+            elsif current_cells.size >= CPU_COUNT || cells != current_cells # At max size or stale
+              collided = false
+            elsif collided && expand_table_unless_stale(current_cells)
+              collided = false
+              redo # Retry with expanded table
+            else
+              collided = true
+            end
+            hash = XorShiftRandom.xorshift(hash)
+
+          elsif try_initialize_cells(x, hash) || cas_base_computed {|current_base| yield current_base}
+            break
+          end
+        end
+        self.hash_code = hash
+      end
+
+      private
+      # Static per-thread hash code key. Shared across all instances to
+      # reduce Thread locals pollution and because adjustments due to
+      # collisions in one table are likely to be appropriate for
+      # others.
+      THREAD_LOCAL_KEY = "#{name}.hash_code".to_sym
+
+      # A thread-local hash code accessor. The code is initially
+      # random, but may be set to a different value upon collisions.
+      def hash_code
+        Thread.current[THREAD_LOCAL_KEY] ||= XorShiftRandom.get
+      end
+
+      def hash_code=(hash)
+        Thread.current[THREAD_LOCAL_KEY] = hash
+      end
+
+      # Sets base and all +cells+ to the given value.
+      def internal_reset(initial_value)
+        current_cells = cells
+        self.base     = initial_value
+        if current_cells
+          current_cells.each do |cell|
+            cell.value = initial_value if cell
+          end
+        end
+      end
+
+      def cas_base_computed
+        cas_base(current_base = base, yield(current_base))
+      end
+
+      def free?
+        !busy?
+      end
+
+      def try_initialize_cells(x, hash)
+        if free? && !cells
+          try_in_busy do
+            unless cells # Recheck under lock
+              new_cells = PowerOfTwoTuple.new(2)
+              new_cells.volatile_set_by_hash(hash, Cell.new(x))
+              self.cells = new_cells
+            end
+          end
+        end
+      end
+
+      def expand_table_unless_stale(current_cells)
+        try_in_busy do
+          if current_cells == cells # Recheck under lock
+            new_cells = current_cells.next_in_size_table
+            current_cells.each_with_index {|x, i| new_cells.volatile_set(i, x)}
+            self.cells = new_cells
+          end
+        end
+      end
+
+      def try_to_install_new_cell(new_cell, hash)
+        try_in_busy do
+          # Recheck under lock
+          if (current_cells = cells) && !current_cells.volatile_get(i = current_cells.hash_to_index(hash))
+            current_cells.volatile_set(i, new_cell)
+          end
+        end
+      end
+
+      def try_in_busy
+        if cas_busy(false, true)
+          begin
+            yield
+          ensure
+            self.busy = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thread_safe/util/volatile.rb

@@ -0,0 +1,62 @@
+module ThreadSafe
+  module Util
+    module Volatile
+      # Provides +volatile+ (in the JVM's sense) attribute accessors implemented atop of the +AtomicReference+s.
+      # Usage:
+      #   class Foo
+      #     extend ThreadSafe::Util::Volatile
+      #     attr_volatile :foo, :bar
+      #
+      #     def initialize(bar)
+      #       super() # must super() into parent initializers before using the volatile attribute accessors
+      #       self.bar = bar
+      #     end
+      #
+      #     def hello
+      #       my_foo = foo # volatile read
+      #       self.foo = 1 # volatile write
+      #       cas_foo(1, 2) # => true | a strong CAS
+      #     end
+      #   end
+      def attr_volatile(*attr_names)
+        return if attr_names.empty?
+        include(Module.new do
+          atomic_ref_setup = attr_names.map {|attr_name| "@__#{attr_name} = ThreadSafe::Util::AtomicReference.new"}
+          initialize_copy_setup = attr_names.zip(atomic_ref_setup).map do |attr_name, ref_setup|
+            "#{ref_setup}(other.instance_variable_get(:@__#{attr_name}).get)"
+          end
+          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+            def initialize(*)
+              super
+              #{atomic_ref_setup.join('; ')}
+            end
+
+            def initialize_copy(other)
+              super
+              #{initialize_copy_setup.join('; ')}
+            end
+          RUBY_EVAL
+
+          attr_names.each do |attr_name|
+            class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+              def #{attr_name}
+                @__#{attr_name}.get
+              end
+
+              def #{attr_name}=(value)
+                @__#{attr_name}.set(value)
+              end
+
+              def compare_and_set_#{attr_name}(old_value, new_value)
+                @__#{attr_name}.compare_and_set(old_value, new_value)
+              end
+            RUBY_EVAL
+
+            alias_method :"cas_#{attr_name}", :"compare_and_set_#{attr_name}"
+            alias_method :"lazy_set_#{attr_name}", :"#{attr_name}="
+          end
+        end)
+      end
+    end
+  end
+end

data/lib/thread_safe/util/volatile_tuple.rb

@@ -0,0 +1,46 @@
+module ThreadSafe
+  module Util
+    # A fixed size array with volatile volatile getters/setters.
+    # Usage:
+    #   arr = VolatileTuple.new(16)
+    #   arr.volatile_set(0, :foo)
+    #   arr.volatile_get(0)    # => :foo
+    #   arr.cas(0, :foo, :bar) # => true
+    #   arr.volatile_get(0)    # => :bar
+    class VolatileTuple
+      include Enumerable
+
+      Tuple = defined?(Rubinius::Tuple) ? Rubinius::Tuple : Array
+
+      def initialize(size)
+        @tuple = tuple = Tuple.new(size)
+        i = 0
+        while i < size
+          tuple[i] = AtomicReference.new
+          i += 1
+        end
+      end
+
+      def volatile_get(i)
+        @tuple[i].get
+      end
+
+      def volatile_set(i, value)
+        @tuple[i].set(value)
+      end
+
+      def compare_and_set(i, old_value, new_value)
+        @tuple[i].compare_and_set(old_value, new_value)
+      end
+      alias_method :cas, :compare_and_set
+
+      def size
+        @tuple.size
+      end
+
+      def each
+        @tuple.each {|ref| yield ref.get}
+      end
+    end
+  end
+end