concurrent-ruby 1.1.5

data/lib/concurrent/tuple.rb

@@ -0,0 +1,86 @@
+require 'concurrent/atomic/atomic_reference'
+
+module Concurrent
+
+  # A fixed size array with volatile (synchronized, thread safe) getters/setters.
+  # Mixes in Ruby's `Enumerable` module for enhanced search, sort, and traversal.
+  #
+  # @example
+  #   tuple = Concurrent::Tuple.new(16)
+  #
+  #   tuple.set(0, :foo)                   #=> :foo  | volatile write
+  #   tuple.get(0)                         #=> :foo  | volatile read
+  #   tuple.compare_and_set(0, :foo, :bar) #=> true  | strong CAS
+  #   tuple.cas(0, :foo, :baz)             #=> false | strong CAS
+  #   tuple.get(0)                         #=> :bar  | volatile read
+  #
+  # @see https://en.wikipedia.org/wiki/Tuple Tuple entry at Wikipedia
+  # @see http://www.erlang.org/doc/reference_manual/data_types.html#id70396 Erlang Tuple
+  # @see http://ruby-doc.org/core-2.2.2/Enumerable.html Enumerable
+  class Tuple
+    include Enumerable
+
+    # The (fixed) size of the tuple.
+    attr_reader :size
+
+    # @!visibility private
+    Tuple = defined?(Rubinius::Tuple) ? Rubinius::Tuple : ::Array
+    private_constant :Tuple
+
+    # Create a new tuple of the given size.
+    #
+    # @param [Integer] size the number of elements in the tuple
+    def initialize(size)
+      @size = size
+      @tuple = tuple = Tuple.new(size)
+      i = 0
+      while i < size
+        tuple[i] = Concurrent::AtomicReference.new
+        i += 1
+      end
+    end
+
+    # Get the value of the element at the given index.
+    #
+    # @param [Integer] i the index from which to retrieve the value
+    # @return [Object] the value at the given index or nil if the index is out of bounds
+    def get(i)
+      return nil if i >= @size || i < 0
+      @tuple[i].get
+    end
+    alias_method :volatile_get, :get
+
+    # Set the element at the given index to the given value
+    #
+    # @param [Integer] i the index for the element to set
+    # @param [Object] value the value to set at the given index
+    #
+    # @return [Object] the new value of the element at the given index or nil if the index is out of bounds
+    def set(i, value)
+      return nil if i >= @size || i < 0
+      @tuple[i].set(value)
+    end
+    alias_method :volatile_set, :set
+
+    # Set the value at the given index to the new value if and only if the current
+    # value matches the given old value.
+    #
+    # @param [Integer] i the index for the element to set
+    # @param [Object] old_value the value to compare against the current value
+    # @param [Object] new_value the value to set at the given index
+    #
+    # @return [Boolean] true if the value at the given element was set else false
+    def compare_and_set(i, old_value, new_value)
+      return false if i >= @size || i < 0
+      @tuple[i].compare_and_set(old_value, new_value)
+    end
+    alias_method :cas, :compare_and_set
+
+    # Calls the given block once for each element in self, passing that element as a parameter.
+    #
+    # @yieldparam [Object] ref the `Concurrent::AtomicReference` object at the current index
+    def each
+      @tuple.each {|ref| yield ref.get}
+    end
+  end
+end

data/lib/concurrent/tvar.rb

@@ -0,0 +1,258 @@
+require 'set'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # A `TVar` is a transactional variable - a single-element container that
+  # is used as part of a transaction - see `Concurrent::atomically`.
+  #
+  # @!macro thread_safe_variable_comparison
+  #
+  # {include:file:docs-source/tvar.md}
+  class TVar < Synchronization::Object
+    safe_initialization!
+
+    # Create a new `TVar` with an initial value.
+    def initialize(value)
+      @value = value
+      @version = 0
+      @lock = Mutex.new
+    end
+
+    # Get the value of a `TVar`.
+    def value
+      Concurrent::atomically do
+        Transaction::current.read(self)
+      end
+    end
+
+    # Set the value of a `TVar`.
+    def value=(value)
+      Concurrent::atomically do
+        Transaction::current.write(self, value)
+      end
+    end
+
+    # @!visibility private
+    def unsafe_value # :nodoc:
+      @value
+    end
+
+    # @!visibility private
+    def unsafe_value=(value) # :nodoc:
+      @value = value
+    end
+
+    # @!visibility private
+    def unsafe_version # :nodoc:
+      @version
+    end
+
+    # @!visibility private
+    def unsafe_increment_version # :nodoc:
+      @version += 1
+    end
+
+    # @!visibility private
+    def unsafe_lock # :nodoc:
+      @lock
+    end
+
+  end
+
+  # Run a block that reads and writes `TVar`s as a single atomic transaction.
+  # With respect to the value of `TVar` objects, the transaction is atomic, in
+  # that it either happens or it does not, consistent, in that the `TVar`
+  # objects involved will never enter an illegal state, and isolated, in that
+  # transactions never interfere with each other. You may recognise these
+  # properties from database transactions.
+  #
+  # There are some very important and unusual semantics that you must be aware of:
+  #
+  # * Most importantly, the block that you pass to atomically may be executed
+  #     more than once. In most cases your code should be free of
+  #     side-effects, except for via TVar.
+  #
+  # * If an exception escapes an atomically block it will abort the transaction.
+  #
+  # * It is undefined behaviour to use callcc or Fiber with atomically.
+  #
+  # * If you create a new thread within an atomically, it will not be part of
+  #     the transaction. Creating a thread counts as a side-effect.
+  #
+  # Transactions within transactions are flattened to a single transaction.
+  #
+  # @example
+  #   a = new TVar(100_000)
+  #   b = new TVar(100)
+  #
+  #   Concurrent::atomically do
+  #     a.value -= 10
+  #     b.value += 10
+  #   end
+  def atomically
+    raise ArgumentError.new('no block given') unless block_given?
+
+    # Get the current transaction
+
+    transaction = Transaction::current
+
+    # Are we not already in a transaction (not nested)?
+
+    if transaction.nil?
+      # New transaction
+
+      begin
+        # Retry loop
+
+        loop do
+
+          # Create a new transaction
+
+          transaction = Transaction.new
+          Transaction::current = transaction
+
+          # Run the block, aborting on exceptions
+
+          begin
+            result = yield
+          rescue Transaction::AbortError => e
+            transaction.abort
+            result = Transaction::ABORTED
+          rescue Transaction::LeaveError => e
+            transaction.abort
+            break result
+          rescue => e
+            transaction.abort
+            raise e
+          end
+          # If we can commit, break out of the loop
+
+          if result != Transaction::ABORTED
+            if transaction.commit
+              break result
+            end
+          end
+        end
+      ensure
+        # Clear the current transaction
+
+        Transaction::current = nil
+      end
+    else
+      # Nested transaction - flatten it and just run the block
+
+      yield
+    end
+  end
+
+  # Abort a currently running transaction - see `Concurrent::atomically`.
+  def abort_transaction
+    raise Transaction::AbortError.new
+  end
+
+  # Leave a transaction without committing or aborting - see `Concurrent::atomically`.
+  def leave_transaction
+    raise Transaction::LeaveError.new
+  end
+
+  module_function :atomically, :abort_transaction, :leave_transaction
+
+  private
+
+  class Transaction
+
+    ABORTED = ::Object.new
+
+    ReadLogEntry = Struct.new(:tvar, :version)
+
+    AbortError = Class.new(StandardError)
+    LeaveError = Class.new(StandardError)
+
+    def initialize
+      @read_log  = []
+      @write_log = {}
+    end
+
+    def read(tvar)
+      Concurrent::abort_transaction unless valid?
+
+      if @write_log.has_key? tvar
+        @write_log[tvar]
+      else
+        @read_log.push(ReadLogEntry.new(tvar, tvar.unsafe_version))
+        tvar.unsafe_value
+      end
+    end
+
+    def write(tvar, value)
+      # Have we already written to this TVar?
+
+      unless @write_log.has_key? tvar
+        # Try to lock the TVar
+
+        unless tvar.unsafe_lock.try_lock
+          # Someone else is writing to this TVar - abort
+          Concurrent::abort_transaction
+        end
+
+        # If we previously wrote to it, check the version hasn't changed
+
+        @read_log.each do |log_entry|
+          if log_entry.tvar == tvar and tvar.unsafe_version > log_entry.version
+            Concurrent::abort_transaction
+          end
+        end
+      end
+
+      # Record the value written
+
+      @write_log[tvar] = value
+    end
+
+    def abort
+      unlock
+    end
+
+    def commit
+      return false unless valid?
+
+      @write_log.each_pair do |tvar, value|
+        tvar.unsafe_value = value
+        tvar.unsafe_increment_version
+      end
+
+      unlock
+
+      true
+    end
+
+    def valid?
+      @read_log.each do |log_entry|
+        unless @write_log.has_key? log_entry.tvar
+          if log_entry.tvar.unsafe_version > log_entry.version
+            return false
+          end
+        end
+      end
+
+      true
+    end
+
+    def unlock
+      @write_log.each_key do |tvar|
+        tvar.unsafe_lock.unlock
+      end
+    end
+
+    def self.current
+      Thread.current[:current_tvar_transaction]
+    end
+
+    def self.current=(transaction)
+      Thread.current[:current_tvar_transaction] = transaction
+    end
+
+  end
+
+end

data/lib/concurrent/utility/at_exit.rb

@@ -0,0 +1,97 @@
+require 'logger'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # Provides ability to add and remove handlers to be run at `Kernel#at_exit`, order is undefined.
+  # Each handler is executed at most once.
+  #
+  # @!visibility private
+  class AtExitImplementation < Synchronization::LockableObject
+    include Logger::Severity
+
+    def initialize(*args)
+      super()
+      synchronize { ns_initialize(*args) }
+    end
+
+    # Add a handler to be run at `Kernel#at_exit`
+    # @param [Object] handler_id optionally provide an id, if already present, handler is replaced
+    # @yield the handler
+    # @return id of the handler
+    def add(handler_id = nil, &handler)
+      id = handler_id || handler.object_id
+      synchronize { @handlers[id] = handler }
+      id
+    end
+
+    # Delete a handler by handler_id
+    # @return [true, false]
+    def delete(handler_id)
+      !!synchronize { @handlers.delete handler_id }
+    end
+
+    # Is handler with handler_id rpesent?
+    # @return [true, false]
+    def handler?(handler_id)
+      synchronize { @handlers.key? handler_id }
+    end
+
+    # @return copy of the handlers
+    def handlers
+      synchronize { @handlers }.clone
+    end
+
+    # install `Kernel#at_exit` callback to execute added handlers
+    def install
+      synchronize do
+        @installed ||= begin
+                         at_exit { runner }
+                         true
+                       end
+        self
+      end
+    end
+
+    # Will it run during `Kernel#at_exit`
+    def enabled?
+      synchronize { @enabled }
+    end
+
+    # Configure if it runs during `Kernel#at_exit`
+    def enabled=(value)
+      synchronize { @enabled = value }
+    end
+
+    # run the handlers manually
+    # @return ids of the handlers
+    def run
+      handlers, _ = synchronize { handlers, @handlers = @handlers, {} }
+      handlers.each do |_, handler|
+        begin
+          handler.call
+        rescue => error
+          Concurrent.global_logger.call(ERROR, error)
+        end
+      end
+      handlers.keys
+    end
+
+    private
+
+    def ns_initialize(enabled = true)
+      @handlers = {}
+      @enabled  = enabled
+    end
+
+    def runner
+      run if synchronize { @enabled }
+    end
+  end
+
+  private_constant :AtExitImplementation
+
+  # @see AtExitImplementation
+  # @!visibility private
+  AtExit = AtExitImplementation.new.install
+end

data/lib/concurrent/utility/engine.rb

@@ -0,0 +1,56 @@
+module Concurrent
+  module Utility
+
+    # @!visibility private
+    module EngineDetector
+      def on_jruby?
+        ruby_engine == 'jruby'
+      end
+
+      def on_jruby_9000?
+        on_jruby? && ruby_version(JRUBY_VERSION, :>=, 9, 0, 0)
+      end
+
+      def on_cruby?
+        ruby_engine == 'ruby'
+      end
+
+      def on_rbx?
+        ruby_engine == 'rbx'
+      end
+
+      def on_truffleruby?
+        ruby_engine == 'truffleruby'
+      end
+
+      def on_windows?
+        !(RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/).nil?
+      end
+
+      def on_osx?
+        !(RbConfig::CONFIG['host_os'] =~ /darwin|mac os/).nil?
+      end
+
+      def on_linux?
+        !(RbConfig::CONFIG['host_os'] =~ /linux/).nil?
+      end
+
+      def ruby_engine
+        defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
+      end
+
+      def ruby_version(version = RUBY_VERSION, comparison, major, minor, patch)
+        result      = (version.split('.').map(&:to_i) <=> [major, minor, patch])
+        comparisons = { :== => [0],
+                        :>= => [1, 0],
+                        :<= => [-1, 0],
+                        :>  => [1],
+                        :<  => [-1] }
+        comparisons.fetch(comparison).include? result
+      end
+    end
+  end
+
+  # @!visibility private
+  extend Utility::EngineDetector
+end