concurrent-ruby 0.9.0.pre3-java → 0.9.1-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 10a5012e42fee5380405d4af4afcbc1057bdda26
-  data.tar.gz: d3a355604220a071410631424fc05288df4a67e6
+  metadata.gz: f83e4336126502153551f929eee369cd8216b18d
+  data.tar.gz: 2c5ff95b7bc1850a2a81e3ed90c0cbe2120e5064
 SHA512:
-  metadata.gz: 3e3bfd78da01a87137ad705c28a0503f057689e64614d4e22fcea1a79d7e29f041a90d36d0dceb16937fa17e8dc66542a4a528ebaee11d0a05ab0c7a901049f8
-  data.tar.gz: 41308b6e724dfa7dbc4a74f979b748b62aa475c8396e7e46234e2c0214910aafb253112f9c413934f97e2123c8831ad394d34cf8c6be251262420ee24b387bca
+  metadata.gz: 204ffe7abafca91f53b32075ea39a4c9cd260c753c7d1dc454b26b6e9e1238c150e3a78e9fce5a498a5d935efcc0e9b217ee20cef3477bc979a5078cb29d7077
+  data.tar.gz: 9d854dad02dbdb4a510d1df469467047b5ab5499341848ffacbe04bd914ba4c437189125a2d690bac474fa178a377df41d79643fa2d001abca6657b0b1ab4cc7

data/CHANGELOG.md

@@ -1,5 +1,18 @@
-### Next Release v0.9.0 (Target Date: 7 June 2015)
+## Current Release v0.9.1 (09 August 2015)
 
+* Fixed a Rubiniux bug in synchronization object
+* Fixed all interpreter warnings (except circular references)
+* Fixed require statements when requiring `Atom` alone
+* Significantly improved `ThreadLocalVar` on non-JRuby platforms
+* Fixed error handling in Edge `Concurrent.zip`
+* `AtomicFixnum` methods `#increment` and `#decrement` now support optional delta
+* New `AtomicFixnum#update` method
+* Minor optimizations in `ReadWriteLock`
+* New `ReentrantReadWriteLock` class
+* `ThreadLocalVar#bind` method is now public
+* Refactored many tests
+
+### Release v0.9.0 (10 July 2015)
 
 * Updated `AtomicReference`
   - `AtomicReference#try_update` now simply returns instead of raising exception
@@ -98,7 +111,7 @@
 * Removed brute-force killing of threads in tests
 * Fixed a thread pool bug when the operating system cannot allocate more threads
 
-## Current Release v0.8.0 (25 January 2015)
+### Release v0.8.0 (25 January 2015)
 
 * C extension for MRI have been extracted into the `concurrent-ruby-ext` companion gem.
   Please see the README for more detail.

data/README.md

@@ -1,5 +1,13 @@
 # Concurrent Ruby
-[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.svg)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.svg)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.svg)](https://gemnasium.com/ruby-concurrency/concurrent-ruby) [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT) [![Gitter chat](http://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
+
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.svg)](http://badge.fury.io/rb/concurrent-ruby)
+[![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby)
+[![Build status](https://ci.appveyor.com/api/projects/status/iq8aboyuu3etad4w?svg=true)](https://ci.appveyor.com/project/rubyconcurrency/concurrent-ruby)
+[![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.svg)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby)
+[![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby)
+[![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.svg)](https://gemnasium.com/ruby-concurrency/concurrent-ruby)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
+[![Gitter chat](https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
 <table>
   <tr>
@@ -39,16 +47,17 @@
 
 MRI 1.9.3, 2.0, 2.1, 2.2, JRuby (1.9 mode), and Rubinius 2.x are supported.
 This gem should be fully compatible with any interpreter that is compliant with Ruby 1.9.3 or newer.
+Java 8 is required for JRuby (Java 7 support is deprecated in version 0.9 and will be removed in 1.0).
 
 ## Features & Documentation
 
-We have a roadmap guiding our work toward the [v1.0.0 release](https://github.com/ruby-concurrency/concurrent-ruby/wiki/v1.0-Roadmap).
+We have a roadmap guiding our work toward the [v1.0.0 release](https://github.com/ruby-concurrency/concurrent-ruby/issues/257).
 
 The primary site for documentation is the automatically generated [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html)
 
-We also have a [mailing list](http://groups.google.com/group/concurrent-ruby).
+We also have a [mailing list](http://groups.google.com/group/concurrent-ruby) and [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).
 
-This library contains a variety of concurrency abstractions at high and low levels. One of the high-level abstractions is likely to meet most common needs. 
+This library contains a variety of concurrency abstractions at high and low levels. One of the high-level abstractions is likely to meet most common needs.
 
 #### General-purpose Concurrency Abstractions
 
@@ -58,7 +67,7 @@ This library contains a variety of concurrency abstractions at high and low leve
   * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
 * [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.
 * [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
-* [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals. 
+* [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals.
 
 #### Thread-safe Value Objects
 
@@ -96,6 +105,7 @@ Derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
 * [Thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
 * [Software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
 * [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html)
+* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html)
 
 ### Edge Features
 
@@ -107,34 +117,31 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
 
 * [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
   Implements the Actor Model, where concurrent actors exchange messages.
-* [new Future Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html) - new 
+* [new Future Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/FutureShortcuts.html) - new
   unified implementation of Futures and Promises which combines Features of previous `Future`,
   `Promise`, `IVar`, `Event`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
-  new synchronization layer to make all the paths **lock-free** with exception of blocking threads on `#wait`.
-  It offers better performance and does not block threads when not required.
+  new synchronization layer to make all the features **non-blocking** and **lock-free** with exception of obviously blocking
+  operations like `#wait`, `#value`. It also offers better performance.
 * [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A single atomic value that represents an identity.
 * [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Channel.html):
   Communicating Sequential Processes (CSP).
 * [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
 * [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
-* [New Future Promise Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html) - new 
-  unified implementation of Futures and Promises which combines Features of previous `Future`,
-  `Promise`, `IVar`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
-  new synchronization layer to make all the paths lock-free with exception of blocking threads on `#wait`.
-  It offers better performance and does not block threads (exception being `#wait` and similar methods where it's
-  intended).
-
+* [Atomic Markable Reference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
+* [LockFreeLinked Set](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
+* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeStack.html)
 
 #### Statuses:
 
-*Why is not in core?*
+*Why are these not in core?*
 
-- **Actor** - partial documentation and tests, stability good. 
-- **Future/Promise Framework** - partial documentation and tests, stability good.
-- **Agent** - incomplete behaviour compared to Clojure's model, stability good.
-- **Channel** - missing documentation, stability good.
-- **Exchanger** - known race issue.
-- **LazyRegister** - missing documentation and tests.   
+- **Actor** - Partial documentation and tests; stability is good.
+- **Future/Promise Framework** - API changes; partial documentation and tests; stability good.
+- **Agent** - Incomplete behaviour compared to Clojure's models; stability good.
+- **Channel** - Missing documentation; limted features; stability good.
+- **Exchanger** - Known race condition requiring a new implementation.
+- **LazyRegister** - Missing documentation and tests.
+- **AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack** - Needs real world battle testing
 
 ## Usage
 
@@ -178,8 +185,6 @@ require 'concurrent/actor'          # Concurrent::Actor and supporting code
 require 'concurrent/edge/future'    # new Future Framework
 require 'concurrent/agent'          # Concurrent::Agent
 require 'concurrent/channel '       # Concurrent::Channel and supporting code
-require 'concurrent/exchanger'      # Concurrent::Exchanger
-require 'concurrent/lazy_register'  # Concurrent::LazyRegister
 ```
 
 If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to reveal the problem.
@@ -248,10 +253,16 @@ bundle exec rake build              # Build JRuby-specific core gem (alias for `
 bundle exec rake build:core         # Build concurrent-ruby-<version>-java.gem into the pkg directory
 
 *All except JRuby*
-bundle exec rake build              # Build core and extension gems
 bundle exec rake build:core         # Build concurrent-ruby-<version>.gem into the pkg directory
 bundle exec rake build:ext          # Build concurrent-ruby-ext-<version>.gem into the pkg directory
 
+*When Docker IS installed*
+bundle exec rake build:windows      # Build the windows binary <version> gems per rake-compiler-dock
+bundle exec rake build              # Build core, extension, and edge gems, including Windows binaries
+
+*When Docker is NOT installed*
+bundle exec rake build              # Build core, extension, and edge gems (excluding Windows binaries)
+
 *All*
 bundle exec rake clean              # Remove any temporary products
 bundle exec rake clobber            # Remove any generated file
@@ -260,7 +271,7 @@ bundle exec rake compile            # Compile all the extensions
 
 ## Maintainers
 
-* [Jerry D'Antonio](https://github.com/jdantonio)
+* [Jerry D'Antonio](https://github.com/jdantonio) (creator)
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
 * [Lucas Allan](https://github.com/lucasallan)

data/lib/concurrent/atomic/atomic_fixnum.rb

@@ -66,22 +66,26 @@ module Concurrent
 
     # @!macro [attach] atomic_fixnum_method_increment
     #
-    #   Increases the current value by 1.
+    #   Increases the current value by the given amount (defaults to 1).
+    #
+    #   @param [Fixnum] delta the amount by which to increase the current value
     #
     #   @return [Fixnum] the current value after incrementation
-    def increment
-      synchronize { ns_set(@value + 1) }
+    def increment(delta = 1)
+      synchronize { ns_set(@value + delta.to_i) }
     end
 
     alias_method :up, :increment
 
     # @!macro [attach] atomic_fixnum_method_decrement
     #
-    #   Decreases the current value by 1.
+    #   Decreases the current value by the given amount (defaults to 1).
+    #
+    #   @param [Fixnum] delta the amount by which to decrease the current value
     #
     #   @return [Fixnum] the current value after decrementation
-    def decrement
-      synchronize { ns_set(@value -1) }
+    def decrement(delta = 1)
+      synchronize { ns_set(@value - delta.to_i) }
     end
 
     alias_method :down, :decrement
@@ -97,8 +101,8 @@ module Concurrent
     #   @return [Fixnum] true if the value was updated else false
     def compare_and_set(expect, update)
       synchronize do
-        if @value == expect
-          @value = update
+        if @value == expect.to_i
+          @value = update.to_i
           true
         else
           false
@@ -106,6 +110,23 @@ module Concurrent
       end
     end
 
+    # @!macro [attach] atomic_fixnum_method_update
+    #
+    # Pass the current value to the given block, replacing it
+    # with the block's result. May retry if the value changes
+    # during the block's execution.
+    #
+    # @yield [Object] Calculate a new value for the atomic reference using
+    #   given (old) value
+    # @yieldparam [Object] old_value the starting value of the atomic reference
+    #
+    # @return [Object] the new value
+    def update
+      synchronize do
+        @value = yield @value
+      end
+    end
+
     protected
 
     # @!visibility private

data/lib/concurrent/atomic/read_write_lock.rb

@@ -1,5 +1,5 @@
 require 'thread'
-require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/atomic_fixnum'
 require 'concurrent/errors'
 require 'concurrent/synchronization'
 
@@ -33,7 +33,7 @@ module Concurrent
     WAITING_WRITER = 1 << 15
 
     # @!visibility private
-    RUNNING_WRITER = 1 << 30
+    RUNNING_WRITER = 1 << 29
 
     # @!visibility private
     MAX_READERS    = WAITING_WRITER - 1
@@ -50,11 +50,11 @@ module Concurrent
     # Each reader increments the counter by 1 when acquiring a read lock
     #   (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 << 30) if the write lock is taken
+    #   write lock, and by (1 << 29) if the write lock is taken
 
     # Create a new `ReadWriteLock` in the unlocked state.
     def initialize
-      @Counter   = AtomicReference.new(0) # single integer which represents lock state
+      @Counter   = AtomicFixnum.new(0) # single integer which represents lock state
       @ReadLock  = Synchronization::Lock.new
       @WriteLock = Synchronization::Lock.new
       ensure_ivar_visibility!
@@ -122,11 +122,11 @@ module Concurrent
             if running_writer?(c)
               @ReadLock.wait_until { !running_writer? }
             else
-              return if @Counter.compare_and_swap(c, c+1)
+              return if @Counter.compare_and_set(c, c+1)
             end
           end
         else
-          break if @Counter.compare_and_swap(c, c+1)
+          break if @Counter.compare_and_set(c, c+1)
         end
       end
       true
@@ -138,7 +138,7 @@ module Concurrent
     def release_read_lock
       while true
         c = @Counter.value
-        if @Counter.compare_and_swap(c, c-1)
+        if @Counter.compare_and_set(c, c-1)
           # If one or more writers were waiting, and we were the last reader, wake a writer up
           if waiting_writer?(c) && running_readers(c) == 1
             @WriteLock.signal
@@ -162,8 +162,8 @@ module Concurrent
 
         if c == 0 # no readers OR writers running
           # if we successfully swap the RUNNING_WRITER bit on, then we can go ahead
-          break if @Counter.compare_and_swap(0, RUNNING_WRITER)
-        elsif @Counter.compare_and_swap(c, c+WAITING_WRITER)
+          break if @Counter.compare_and_set(0, RUNNING_WRITER)
+        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)
@@ -180,7 +180,7 @@ module Concurrent
             # Then we are OK to stop waiting and go ahead
             # Otherwise go back and wait again
             c = @Counter.value
-            break if !running_writer?(c) && !running_readers?(c) && @Counter.compare_and_swap(c, c+RUNNING_WRITER-WAITING_WRITER)
+            break if !running_writer?(c) && !running_readers?(c) && @Counter.compare_and_set(c, c+RUNNING_WRITER-WAITING_WRITER)
           end
           break
         end
@@ -192,7 +192,7 @@ module Concurrent
     #
     # @return [Boolean] true if the lock is successfully released
     def release_write_lock
-      c = @Counter.update { |c| c-RUNNING_WRITER }
+      c = @Counter.update { |counter| counter-RUNNING_WRITER }
       @ReadLock.broadcast
       @WriteLock.signal if waiting_writers(c) > 0
       true

data/lib/concurrent/atomic/reentrant_read_write_lock.rb

@@ -0,0 +1,375 @@
+require 'thread'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/errors'
+require 'concurrent/synchronization'
+require 'concurrent/atomic/thread_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.
+  #
+  # 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
+
+    # Create a new `ReentrantReadWriteLock` in the unlocked state.
+    def initialize
+      @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  = ThreadLocalVar.new(0)     # indicates # of R & W locks held by this thread
+      ensure_ivar_visibility!
+    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 c == held
+          # If we successfully swap the RUNNING_WRITER bit on, then we can go ahead
+          if @Counter.compare_and_set(c, c+RUNNING_WRITER)
+            @HeldCount.value = held + WRITE_LOCK_HELD
+            return true
+          end
+        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