Improvements for documentation layout

Author: rranelli

lib/thread_safe/atomic_reference_cache_backend.rb

@@ -1,14 +1,21 @@
 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.
+    # 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.
+    # 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.
+    # 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)

lib/thread_safe/mri_cache_backend.rb

@@ -1,7 +1,9 @@
 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.
+    # 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

lib/thread_safe/non_concurrent_cache_backend.rb

@@ -2,7 +2,8 @@ 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.
+    # WARNING: Mutex_m is a non-reentrant lock, so the synchronized methods are
+    # not allowed to call each other.
 
     def [](key)
       synchronize { super }

lib/thread_safe/synchronized_cache_backend.rb

@@ -9,9 +9,9 @@
 #   array = SynchronizedDelegator.new([]) # thread-safe
 #
 # A simple `Monitor` provides a very coarse-grained way to synchronize a given
-# object, in that it will cause synchronization for methods that have no
-# need for it, but this is a trivial way to get thread-safety where none may
-# exist currently on some implementations.
+# object, in that it will cause synchronization for methods that have no need
+# for it, but this is a trivial way to get thread-safety where none may exist
+# currently on some implementations.
 #
 # This class is currently being considered for inclusion into stdlib, via
 # https://bugs.ruby-lang.org/issues/8556

lib/thread_safe/synchronized_delegator.rb

@@ -1,7 +1,10 @@
 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
+    # 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,

lib/thread_safe/util/adder.rb

@@ -1,6 +1,7 @@
 module ThreadSafe
   module Util
-    # Provides a cheapest possible (mainly in terms of memory usage) +Mutex+ with the +ConditionVariable+ bundled in.
+    # Provides a cheapest possible (mainly in terms of memory usage) +Mutex+
+    # with the +ConditionVariable+ bundled in.
     #
     # Usage:
     #   class A

lib/thread_safe/util/cheap_lockable.rb

@@ -1,69 +1,65 @@
 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
+    # A Ruby port of the Doug Lea's jsr166e.Striped64 class version 1.6
+    # available in public domain.
     #
-    # Class holding common representation and mechanics for classes supporting dynamic striping on 64bit values.
+    # Original source code available here:
+    # http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/jsr166e/Striped64.java?revision=1.6
     #
-    # 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.
+    # Class holding common representation and mechanics for classes supporting
+    # dynamic striping on 64bit values.
     #
-    # 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 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
+    # 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.
+    # 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.
+    # 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.
+    # 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
+    # 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.
@@ -85,8 +81,8 @@ def cas_computed
 
       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.
+      :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
 

lib/thread_safe/util/striped64.rb

@@ -1,7 +1,9 @@
 module ThreadSafe
   module Util
-    # A xorshift random number (positive +Fixnum+s) generator, provides reasonably cheap way to generate thread local random numbers without contending for
-    # the global +Kernel.rand+.
+    # A xorshift random number (positive +Fixnum+s) generator, provides
+    # reasonably cheap way to generate thread local random numbers without
+    # contending for the global +Kernel.rand+.
+    #
     # Usage:
     #   x = XorShiftRandom.get # uses Kernel.rand to generate an initial seed
     #   while true