Merge pull request #8 from rranelli/use-yard-for-documentation

jdantonio · jdantonio · commit f321ee87dfbd · 2015-03-08T17:50:50.000-04:00
Use yard for documentation
diff --git a/.gitignore b/.gitignore
@@ -4,7 +4,8 @@
 .bundle
 .config
 /.idea
-.yardoc
+.yardoc/*
+yardoc/*
 Gemfile.lock
 InstalledFiles
 _yardoc
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1,13 @@
+--protected
+--no-private
+--embed-mixins
+--output-dir ./yardoc
+--markup markdown
+--title=Concurrent Ruby
+--template default
+--template-path ./yard-template
+
+./lib/**/*.rb
+-
+README.md
+LICENSE
diff --git a/Gemfile b/Gemfile
@@ -2,3 +2,11 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in thread_safe.gemspec
 gemspec
+
+group :documentation do
+  gem 'countloc', '~> 0.4.0', :platforms => :mri, :require => false
+  gem 'rubycritic', '~> 1.0.2', :platforms => :mri, require: false
+  gem 'yard', '~> 0.8.7.4', :require => false
+  gem 'inch', '~> 0.4.6', :platforms => :mri, :require => false
+  gem 'redcarpet', '~> 3.1.2', platforms: :mri # understands github markdown
+end
diff --git a/lib/thread_safe/atomic_reference_cache_backend.rb b/lib/thread_safe/atomic_reference_cache_backend.rb
diff --git a/lib/thread_safe/mri_cache_backend.rb b/lib/thread_safe/mri_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)
diff --git a/lib/thread_safe/non_concurrent_cache_backend.rb b/lib/thread_safe/non_concurrent_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
diff --git a/lib/thread_safe/synchronized_cache_backend.rb b/lib/thread_safe/synchronized_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 }
diff --git a/lib/thread_safe/synchronized_delegator.rb b/lib/thread_safe/synchronized_delegator.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
diff --git a/lib/thread_safe/util/adder.rb b/lib/thread_safe/util/adder.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,
diff --git a/lib/thread_safe/util/cheap_lockable.rb b/lib/thread_safe/util/cheap_lockable.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
diff --git a/lib/thread_safe/util/striped64.rb b/lib/thread_safe/util/striped64.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
 
diff --git a/lib/thread_safe/util/xor_shift_random.rb b/lib/thread_safe/util/xor_shift_random.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
diff --git a/yard-template/default/fulldoc/html/css/common.css b/yard-template/default/fulldoc/html/css/common.css
@@ -0,0 +1,125 @@
+/* Override this file with custom rules */
+
+body {
+    line-height: 18px;
+}
+
+.docstring code, .docstring .object_link a, #filecontents code {
+    padding: 0px 3px 1px 3px;
+    border: 1px solid #eef;
+    background: #f5f5ff;
+}
+
+#filecontents pre code, .docstring pre code {
+    border: none;
+    background: none;
+    padding: 0;
+}
+
+#filecontents pre.code, .docstring pre.code, .tags pre.example, .docstring code, .docstring .object_link a,
+#filecontents code {
+    -moz-border-radius: 2px;
+    -webkit-border-radius: 2px;
+}
+
+/* syntax highlighting */
+.source_code {
+    display: none;
+    padding: 3px 8px;
+    border-left: 8px solid #ddd;
+    margin-top: 5px;
+}
+
+#filecontents pre.code, .docstring pre.code, .source_code pre {
+    font-family: monospace;
+}
+
+#filecontents pre.code, .docstring pre.code {
+    display: block;
+}
+
+.source_code .lines {
+    padding-right: 12px;
+    color: #555;
+    text-align: right;
+}
+
+#filecontents pre.code, .docstring pre.code,
+.tags pre.example {
+    padding: 5px 12px;
+    margin-top: 4px;
+    border: 1px solid #eef;
+    background: #f5f5ff;
+}
+
+pre.code {
+    color: #000;
+}
+
+pre.code .info.file {
+    color: #555;
+}
+
+pre.code .val {
+    color: #036A07;
+}
+
+pre.code .tstring_content,
+pre.code .heredoc_beg, pre.code .heredoc_end,
+pre.code .qwords_beg, pre.code .qwords_end,
+pre.code .tstring, pre.code .dstring {
+    color: #036A07;
+}
+
+pre.code .fid,
+pre.code .rubyid_new,
+pre.code .rubyid_to_s,
+pre.code .rubyid_to_sym,
+pre.code .rubyid_to_f,
+pre.code .rubyid_to_i,
+pre.code .rubyid_each {
+    color: inherit;
+}
+
+pre.code .comment {
+    color: #777;
+    font-style: italic;
+}
+
+pre.code .const, pre.code .constant {
+    color: inherit;
+    font-weight: bold;
+    font-style: italic;
+}
+
+pre.code .label,
+pre.code .symbol {
+    color: #C5060B;
+}
+
+pre.code .kw,
+pre.code .rubyid_require,
+pre.code .rubyid_extend,
+pre.code .rubyid_include,
+pre.code .int {
+    color: #0000FF;
+}
+
+pre.code .ivar {
+    color: #660E7A;
+}
+
+pre.code .gvar,
+pre.code .rubyid_backref,
+pre.code .rubyid_nth_ref {
+    color: #6D79DE;
+}
+
+pre.code .regexp, .dregexp {
+    color: #036A07;
+}
+
+pre.code a {
+    border-bottom: 1px dotted #bbf;
+}
+
diff --git a/yard-template/default/layout/html/footer.erb b/yard-template/default/layout/html/footer.erb

Original file line number	Diff line number	Diff line change
`@@ -9,9 +9,9 @@`
`9`	`9`	`# array = SynchronizedDelegator.new([]) # thread-safe`
`10`	`10`	`#`
`11`	`11`	# A simple `Monitor` provides a very coarse-grained way to synchronize a given
`12`		`-# object, in that it will cause synchronization for methods that have no`
`13`		`-# need for it, but this is a trivial way to get thread-safety where none may`
`14`		`-# exist currently on some implementations.`
	`12`	`+# object, in that it will cause synchronization for methods that have no need`
	`13`	`+# for it, but this is a trivial way to get thread-safety where none may exist`
	`14`	`+# currently on some implementations.`
`15`	`15`	`#`
`16`	`16`	`# This class is currently being considered for inclusion into stdlib, via`
`17`	`17`	`# https://bugs.ruby-lang.org/issues/8556`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`module ThreadSafe`
`2`	`2`	`module Util`
`3`		`- # Provides a cheapest possible (mainly in terms of memory usage) +Mutex+ with the +ConditionVariable+ bundled in.`
	`3`	`+ # Provides a cheapest possible (mainly in terms of memory usage) +Mutex+`
	`4`	`+ # with the +ConditionVariable+ bundled in.`
`4`	`5`	`#`
`5`	`6`	`# Usage:`
`6`	`7`	`# class A`