pangea-core 0.1.0 → 0.3.0

data/vendor/bundle/ruby/3.3.0/gems/concurrent-ruby-1.3.6/lib/concurrent-ruby/concurrent/atomic/reentrant_read_write_lock.rb

@@ -0,0 +1,379 @@
+require 'thread'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/atomic_fixnum'
+require 'concurrent/errors'
+require 'concurrent/synchronization/object'
+require 'concurrent/synchronization/lock'
+require 'concurrent/atomic/lock_local_var'
+
+module Concurrent
+
+  # Re-entrant read-write lock implementation
+  #
+  # Allows any number of concurrent readers, but only one concurrent writer
+  # (And while the "write" lock is taken, no read locks can be obtained either.
+  # Hence, the write lock can also be called an "exclusive" lock.)
+  #
+  # If another thread has taken a read lock, any thread which wants a write lock
+  # will block until all the readers release their locks. However, once a thread
+  # starts waiting to obtain a write lock, any additional readers that come along
+  # will also wait (so writers are not starved).
+  #
+  # A thread can acquire both a read and write lock at the same time. A thread can
+  # also acquire a read lock OR a write lock more than once. Only when the read (or
+  # write) lock is released as many times as it was acquired, will the thread
+  # actually let it go, allowing other threads which might have been waiting
+  # to proceed. Therefore the lock can be upgraded by first acquiring
+  # read lock and then write lock and that the lock can be downgraded by first
+  # having both read and write lock a releasing just the write lock.
+  #
+  # If both read and write locks are acquired by the same thread, it is not strictly
+  # necessary to release them in the same order they were acquired. In other words,
+  # the following code is legal:
+  #
+  # @example
+  #   lock = Concurrent::ReentrantReadWriteLock.new
+  #   lock.acquire_write_lock
+  #   lock.acquire_read_lock
+  #   lock.release_write_lock
+  #   # At this point, the current thread is holding only a read lock, not a write
+  #   # lock. So other threads can take read locks, but not a write lock.
+  #   lock.release_read_lock
+  #   # Now the current thread is not holding either a read or write lock, so
+  #   # another thread could potentially acquire a write lock.
+  #
+  # This implementation was inspired by `java.util.concurrent.ReentrantReadWriteLock`.
+  #
+  # @example
+  #   lock = Concurrent::ReentrantReadWriteLock.new
+  #   lock.with_read_lock  { data.retrieve }
+  #   lock.with_write_lock { data.modify! }
+  #
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html java.util.concurrent.ReentrantReadWriteLock
+  class ReentrantReadWriteLock < Synchronization::Object
+
+    # Implementation notes:
+    #
+    # A goal is to make the uncontended path for both readers/writers mutex-free
+    # Only if there is reader-writer or writer-writer contention, should mutexes be used
+    # Otherwise, a single CAS operation is all we need to acquire/release a lock
+    #
+    # Internal state is represented by a single integer ("counter"), and updated
+    #   using atomic compare-and-swap operations
+    # When the counter is 0, the lock is free
+    # Each thread which has one OR MORE read locks increments the counter by 1
+    #   (and decrements by 1 when releasing the read lock)
+    # The counter is increased by (1 << 15) for each writer waiting to acquire the
+    #   write lock, and by (1 << 29) if the write lock is taken
+    #
+    # Additionally, each thread uses a thread-local variable to count how many times
+    #   it has acquired a read lock, AND how many times it has acquired a write lock.
+    # It uses a similar trick; an increment of 1 means a read lock was taken, and
+    #   an increment of (1 << 15) means a write lock was taken
+    # This is what makes re-entrancy possible
+    #
+    # 2 rules are followed to ensure good liveness properties:
+    # 1) Once a writer has queued up and is waiting for a write lock, no other thread
+    #    can take a lock without waiting
+    # 2) When a write lock is released, readers are given the "first chance" to wake
+    #    up and acquire a read lock
+    # Following these rules means readers and writers tend to "take turns", so neither
+    #   can starve the other, even under heavy contention
+
+    # @!visibility private
+    READER_BITS    = 15
+    # @!visibility private
+    WRITER_BITS    = 14
+
+    # Used with @Counter:
+    # @!visibility private
+    WAITING_WRITER = 1 << READER_BITS
+    # @!visibility private
+    RUNNING_WRITER = 1 << (READER_BITS + WRITER_BITS)
+    # @!visibility private
+    MAX_READERS    = WAITING_WRITER - 1
+    # @!visibility private
+    MAX_WRITERS    = RUNNING_WRITER - MAX_READERS - 1
+
+    # Used with @HeldCount:
+    # @!visibility private
+    WRITE_LOCK_HELD = 1 << READER_BITS
+    # @!visibility private
+    READ_LOCK_MASK  = WRITE_LOCK_HELD - 1
+    # @!visibility private
+    WRITE_LOCK_MASK = MAX_WRITERS
+
+    safe_initialization!
+
+    # Create a new `ReentrantReadWriteLock` in the unlocked state.
+    def initialize
+      super()
+      @Counter    = AtomicFixnum.new(0)       # single integer which represents lock state
+      @ReadQueue  = Synchronization::Lock.new # used to queue waiting readers
+      @WriteQueue = Synchronization::Lock.new # used to queue waiting writers
+      @HeldCount  = LockLocalVar.new(0) # indicates # of R & W locks held by this thread
+    end
+
+    # Execute a block operation within a read lock.
+    #
+    # @yield the task to be performed within the lock.
+    #
+    # @return [Object] the result of the block operation.
+    #
+    # @raise [ArgumentError] when no block is given.
+    # @raise [Concurrent::ResourceLimitError] if the maximum number of readers
+    #   is exceeded.
+    def with_read_lock
+      raise ArgumentError.new('no block given') unless block_given?
+      acquire_read_lock
+      begin
+        yield
+      ensure
+        release_read_lock
+      end
+    end
+
+    # Execute a block operation within a write lock.
+    #
+    # @yield the task to be performed within the lock.
+    #
+    # @return [Object] the result of the block operation.
+    #
+    # @raise [ArgumentError] when no block is given.
+    # @raise [Concurrent::ResourceLimitError] if the maximum number of readers
+    #   is exceeded.
+    def with_write_lock
+      raise ArgumentError.new('no block given') unless block_given?
+      acquire_write_lock
+      begin
+        yield
+      ensure
+        release_write_lock
+      end
+    end
+
+    # Acquire a read lock. If a write lock is held by another thread, will block
+    # until it is released.
+    #
+    # @return [Boolean] true if the lock is successfully acquired
+    #
+    # @raise [Concurrent::ResourceLimitError] if the maximum number of readers
+    #   is exceeded.
+    def acquire_read_lock
+      if (held = @HeldCount.value) > 0
+        # If we already have a lock, there's no need to wait
+        if held & READ_LOCK_MASK == 0
+          # But we do need to update the counter, if we were holding a write
+          #   lock but not a read lock
+          @Counter.update { |c| c + 1 }
+        end
+        @HeldCount.value = held + 1
+        return true
+      end
+
+      while true
+        c = @Counter.value
+        raise ResourceLimitError.new('Too many reader threads') if max_readers?(c)
+
+        # If a writer is waiting OR running when we first queue up, we need to wait
+        if waiting_or_running_writer?(c)
+          # Before going to sleep, check again with the ReadQueue mutex held
+          @ReadQueue.synchronize do
+            @ReadQueue.ns_wait if waiting_or_running_writer?
+          end
+          # Note: the above 'synchronize' block could have used #wait_until,
+          #   but that waits repeatedly in a loop, checking the wait condition
+          #   each time it wakes up (to protect against spurious wakeups)
+          # But we are already in a loop, which is only broken when we successfully
+          #   acquire the lock! So we don't care about spurious wakeups, and would
+          #   rather not pay the extra overhead of using #wait_until
+
+          # After a reader has waited once, they are allowed to "barge" ahead of waiting writers
+          # But if a writer is *running*, the reader still needs to wait (naturally)
+          while true
+            c = @Counter.value
+            if running_writer?(c)
+              @ReadQueue.synchronize do
+                @ReadQueue.ns_wait if running_writer?
+              end
+            elsif @Counter.compare_and_set(c, c+1)
+              @HeldCount.value = held + 1
+              return true
+            end
+          end
+        elsif @Counter.compare_and_set(c, c+1)
+          @HeldCount.value = held + 1
+          return true
+        end
+      end
+    end
+
+    # Try to acquire a read lock and return true if we succeed. If it cannot be
+    # acquired immediately, return false.
+    #
+    # @return [Boolean] true if the lock is successfully acquired
+    def try_read_lock
+      if (held = @HeldCount.value) > 0
+        if held & READ_LOCK_MASK == 0
+          # If we hold a write lock, but not a read lock...
+          @Counter.update { |c| c + 1 }
+        end
+        @HeldCount.value = held + 1
+        return true
+      else
+        c = @Counter.value
+        if !waiting_or_running_writer?(c) && @Counter.compare_and_set(c, c+1)
+          @HeldCount.value = held + 1
+          return true
+        end
+      end
+      false
+    end
+
+    # Release a previously acquired read lock.
+    #
+    # @return [Boolean] true if the lock is successfully released
+    def release_read_lock
+      held = @HeldCount.value = @HeldCount.value - 1
+      rlocks_held = held & READ_LOCK_MASK
+      if rlocks_held == 0
+        c = @Counter.update { |counter| counter - 1 }
+        # If one or more writers were waiting, and we were the last reader, wake a writer up
+        if waiting_or_running_writer?(c) && running_readers(c) == 0
+          @WriteQueue.signal
+        end
+      elsif rlocks_held == READ_LOCK_MASK
+        raise IllegalOperationError, "Cannot release a read lock which is not held"
+      end
+      true
+    end
+
+    # Acquire a write lock. Will block and wait for all active readers and writers.
+    #
+    # @return [Boolean] true if the lock is successfully acquired
+    #
+    # @raise [Concurrent::ResourceLimitError] if the maximum number of writers
+    #   is exceeded.
+    def acquire_write_lock
+      if (held = @HeldCount.value) >= WRITE_LOCK_HELD
+        # if we already have a write (exclusive) lock, there's no need to wait
+        @HeldCount.value = held + WRITE_LOCK_HELD
+        return true
+      end
+
+      while true
+        c = @Counter.value
+        raise ResourceLimitError.new('Too many writer threads') if max_writers?(c)
+
+        # To go ahead and take the lock without waiting, there must be no writer
+        #   running right now, AND no writers who came before us still waiting to
+        #   acquire the lock
+        # Additionally, if any read locks have been taken, we must hold all of them
+        if held > 0 && @Counter.compare_and_set(1, c+RUNNING_WRITER)
+          # If we are the only one reader and successfully swap the RUNNING_WRITER bit on, then we can go ahead
+          @HeldCount.value = held + WRITE_LOCK_HELD
+          return true
+        elsif @Counter.compare_and_set(c, c+WAITING_WRITER)
+          while true
+            # Now we have successfully incremented, so no more readers will be able to increment
+            #   (they will wait instead)
+            # However, readers OR writers could decrement right here
+            @WriteQueue.synchronize do
+              # So we have to do another check inside the synchronized section
+              # If a writer OR another reader is running, then go to sleep
+              c = @Counter.value
+              @WriteQueue.ns_wait if running_writer?(c) || running_readers(c) != held
+            end
+            # Note: if you are thinking of replacing the above 'synchronize' block
+            # with #wait_until, read the comment in #acquire_read_lock first!
+
+            # We just came out of a wait
+            # If we successfully turn the RUNNING_WRITER bit on with an atomic swap,
+            #   then we are OK to stop waiting and go ahead
+            # Otherwise go back and wait again
+            c = @Counter.value
+            if !running_writer?(c) &&
+               running_readers(c) == held &&
+               @Counter.compare_and_set(c, c+RUNNING_WRITER-WAITING_WRITER)
+              @HeldCount.value = held + WRITE_LOCK_HELD
+              return true
+            end
+          end
+        end
+      end
+    end
+
+    # Try to acquire a write lock and return true if we succeed. If it cannot be
+    # acquired immediately, return false.
+    #
+    # @return [Boolean] true if the lock is successfully acquired
+    def try_write_lock
+      if (held = @HeldCount.value) >= WRITE_LOCK_HELD
+        @HeldCount.value = held + WRITE_LOCK_HELD
+        return true
+      else
+        c = @Counter.value
+        if !waiting_or_running_writer?(c) &&
+           running_readers(c) == held &&
+           @Counter.compare_and_set(c, c+RUNNING_WRITER)
+           @HeldCount.value = held + WRITE_LOCK_HELD
+          return true
+        end
+      end
+      false
+    end
+
+    # Release a previously acquired write lock.
+    #
+    # @return [Boolean] true if the lock is successfully released
+    def release_write_lock
+      held = @HeldCount.value = @HeldCount.value - WRITE_LOCK_HELD
+      wlocks_held = held & WRITE_LOCK_MASK
+      if wlocks_held == 0
+        c = @Counter.update { |counter| counter - RUNNING_WRITER }
+        @ReadQueue.broadcast
+        @WriteQueue.signal if waiting_writers(c) > 0
+      elsif wlocks_held == WRITE_LOCK_MASK
+        raise IllegalOperationError, "Cannot release a write lock which is not held"
+      end
+      true
+    end
+
+    private
+
+    # @!visibility private
+    def running_readers(c = @Counter.value)
+      c & MAX_READERS
+    end
+
+    # @!visibility private
+    def running_readers?(c = @Counter.value)
+      (c & MAX_READERS) > 0
+    end
+
+    # @!visibility private
+    def running_writer?(c = @Counter.value)
+      c >= RUNNING_WRITER
+    end
+
+    # @!visibility private
+    def waiting_writers(c = @Counter.value)
+      (c & MAX_WRITERS) >> READER_BITS
+    end
+
+    # @!visibility private
+    def waiting_or_running_writer?(c = @Counter.value)
+      c >= WAITING_WRITER
+    end
+
+    # @!visibility private
+    def max_readers?(c = @Counter.value)
+      (c & MAX_READERS) == MAX_READERS
+    end
+
+    # @!visibility private
+    def max_writers?(c = @Counter.value)
+      (c & MAX_WRITERS) == MAX_WRITERS
+    end
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/concurrent-ruby-1.3.6/lib/concurrent-ruby/concurrent/atomic/semaphore.rb

@@ -0,0 +1,163 @@
+require 'concurrent/atomic/mutex_semaphore'
+
+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
+
+  # @!macro semaphore_method_acquire
+  #
+  #   Acquires the given number of permits from this semaphore,
+  #     blocking until all are available. If a block is given,
+  #     yields to it and releases the permits afterwards.
+  #
+  #   @param [Fixnum] permits Number of permits to acquire
+  #
+  #   @raise [ArgumentError] if `permits` is not an integer or is less than zero
+  #
+  #   @return [nil, BasicObject] Without a block, `nil` is returned. If a block
+  #   is given, its return value is returned.
+
+  # @!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. If a block is given, yields to it if the permits
+  #     were successfully acquired, and releases them afterward, returning the
+  #     block's return value.
+  #
+  #   @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 zero
+  #
+  #   @return [true, false, nil, BasicObject] `false` if no permits are
+  #     available, `true` when acquired a permit. If a block is given, the
+  #     block's return value is returned if the permits were acquired; if not,
+  #     `nil` is returned.
+
+  # @!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 zero
+  #
+  #   @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 = if Concurrent.on_jruby?
+                              require 'concurrent/utility/native_extension_loader'
+                              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.
+  #   Alternatively, permits may be acquired within a block, and automatically
+  #   released after the block finishes executing.
+  #
+  # @!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
+  #
+  # @example
+  #   semaphore = Concurrent::Semaphore.new(1)
+  #
+  #   puts semaphore.available_permits
+  #   semaphore.acquire do
+  #     puts semaphore.available_permits
+  #   end
+  #   puts semaphore.available_permits
+  #
+  #   # prints:
+  #   # 1
+  #   # 0
+  #   # 1
+  class Semaphore < SemaphoreImplementation
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/concurrent-ruby-1.3.6/lib/concurrent-ruby/concurrent/atomic/thread_local_var.rb

@@ -0,0 +1,111 @@
+require 'concurrent/constants'
+require_relative 'locals'
+
+module Concurrent
+
+  # 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.
+  #
+  # This is similar to Ruby's built-in thread-local variables (`Thread#thread_variable_get`),
+  # but with these major advantages:
+  # * `ThreadLocalVar` has its own identity, it doesn't need a Symbol.
+  # * Each Ruby's built-in thread-local variable leaks some memory forever (it's a Symbol held forever on the thread),
+  #   so it's only OK to create a small amount of them.
+  #   `ThreadLocalVar` has no such issue and it is fine to create many of them.
+  # * Ruby's built-in thread-local variables leak forever the value set on each thread (unless set to nil explicitly).
+  #   `ThreadLocalVar` automatically removes the mapping for each thread once the `ThreadLocalVar` instance is GC'd.
+  #
+  # @!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
+  class ThreadLocalVar
+    LOCALS = ThreadLocals.new
+
+    # 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
+    def initialize(default = nil, &default_block)
+      if default && block_given?
+        raise ArgumentError, "Cannot use both value and block as default value"
+      end
+
+      if block_given?
+        @default_block = default_block
+        @default = nil
+      else
+        @default_block = nil
+        @default = default
+      end
+
+      @index = LOCALS.next_index(self)
+    end
+
+    # Returns the value in the current thread's copy of this thread-local variable.
+    #
+    # @return [Object] the current value
+    def value
+      LOCALS.fetch(@index) { default }
+    end
+
+    # 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
+    def value=(value)
+      LOCALS.set(@index, value)
+    end
+
+    # 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
+    def bind(value)
+      if block_given?
+        old_value = self.value
+        self.value = value
+        begin
+          yield
+        ensure
+          self.value = old_value
+        end
+      end
+    end
+
+    protected
+
+    # @!visibility private
+    def default
+      if @default_block
+        self.value = @default_block.call
+      else
+        @default
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/concurrent-ruby-1.3.6/lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb

@@ -0,0 +1,37 @@
+require 'concurrent/errors'
+
+module Concurrent
+
+  # Define update methods that use direct paths
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
+  module AtomicDirectUpdate
+    def update
+      true until compare_and_set(old_value = get, new_value = yield(old_value))
+      new_value
+    end
+
+    def try_update
+      old_value = get
+      new_value = yield old_value
+
+      return unless compare_and_set old_value, new_value
+
+      new_value
+    end
+
+    def try_update!
+      old_value = get
+      new_value = yield old_value
+      unless compare_and_set(old_value, new_value)
+        if $VERBOSE
+          raise ConcurrentUpdateError, "Update failed"
+        else
+          raise ConcurrentUpdateError, "Update failed", ConcurrentUpdateError::CONC_UP_ERR_BACKTRACE
+        end
+      end
+      new_value
+    end
+  end
+end