thread_safe 0.3.4 → 0.3.5

data/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)

data/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

data/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 }

data/lib/thread_safe/synchronized_delegator.rb

@@ -9,9 +9,9 @@ require 'monitor'
 #   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

data/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,

data/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

data/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 @@ module ThreadSafe
 
       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
 

data/lib/thread_safe/util/volatile.rb

@@ -1,7 +1,9 @@
 module ThreadSafe
   module Util
     module Volatile
-      # Provides +volatile+ (in the JVM's sense) attribute accessors implemented atop of the +AtomicReference+s.
+      # Provides +volatile+ (in the JVM's sense) attribute accessors implemented
+      # atop of the +AtomicReference+s.
+      #
       # Usage:
       #   class Foo
       #     extend ThreadSafe::Util::Volatile

data/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

data/lib/thread_safe/version.rb

@@ -1,5 +1,5 @@
 module ThreadSafe
-  VERSION = "0.3.4"
+  VERSION = "0.3.5"
 end
 
 # NOTE: <= 0.2.0 used Threadsafe::VERSION

data/tasks/update_doc.rake

@@ -0,0 +1,45 @@
+require 'yard'
+YARD::Rake::YardocTask.new
+
+root = File.expand_path File.join(File.dirname(__FILE__), '..')
+
+namespace :yard do
+
+  cmd = lambda do |command|
+    puts ">> executing: #{command}"
+    system command or raise "#{command} failed"
+  end
+
+  desc 'Pushes generated documentation to github pages: http://ruby-concurrency.github.io/thread_safe/'
+  task :push => [:setup, :yard] do
+
+    message = Dir.chdir(root) do
+      `git log -n 1 --oneline`.strip
+    end
+    puts "Generating commit: #{message}"
+
+    Dir.chdir "#{root}/yardoc" do
+      cmd.call "git add -A"
+      cmd.call "git commit -m '#{message}'"
+      cmd.call 'git push origin gh-pages'
+    end
+
+  end
+
+  desc 'Setups second clone in ./yardoc dir for pushing doc to github'
+  task :setup do
+
+    unless File.exist? "#{root}/yardoc/.git"
+      cmd.call "rm -rf #{root}/yardoc" if File.exist?("#{root}/yardoc")
+      Dir.chdir "#{root}" do
+        cmd.call 'git clone --single-branch --branch gh-pages git@github.com:ruby-concurrency/thread_safe.git ./yardoc'
+      end
+    end
+    Dir.chdir "#{root}/yardoc" do
+      cmd.call 'git fetch origin'
+      cmd.call 'git reset --hard origin/gh-pages'
+    end
+
+  end
+
+end

data/test/test_array.rb

@@ -4,7 +4,7 @@ require File.join(File.dirname(__FILE__), "test_helper")
 class TestArray < Minitest::Test
   def test_concurrency
     ary = ThreadSafe::Array.new
-    (1..100).map do |i|
+    (1..THREADS).map do |i|
       Thread.new do
         1000.times do
           ary << i

data/test/test_cache.rb

@@ -11,7 +11,7 @@ class TestCache < Minitest::Test
 
   def test_concurrency
     cache = @cache
-    (1..100).map do |i|
+    (1..THREADS).map do |i|
       Thread.new do
         1000.times do |j|
           key = i*1000+j

data/test/test_hash.rb

@@ -4,7 +4,7 @@ require File.join(File.dirname(__FILE__), "test_helper")
 class TestHash < Minitest::Test
   def test_concurrency
     hsh = ThreadSafe::Hash.new
-    (1..100).map do |i|
+    (1..THREADS).map do |i|
       Thread.new do
         1000.times do |j|
           hsh[i*1000+j] = i

data/test/test_helper.rb

@@ -1,14 +1,35 @@
-require 'thread'
-require 'rubygems'
-gem 'minitest', '>= 4'
+unless defined?(JRUBY_VERSION)
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+    SimpleCov::Formatter::HTMLFormatter,
+    Coveralls::SimpleCov::Formatter
+  ]
+
+  SimpleCov.start do
+    project_name 'thread_safe'
+
+    add_filter '/examples/'
+    add_filter '/pkg/'
+    add_filter '/test/'
+    add_filter '/tasks/'
+    add_filter '/yard-template/'
+    add_filter '/yardoc/'
+
+    command_name 'Mintest'
+  end
+end
+
 require 'minitest/autorun'
 
-if Minitest.const_defined?('Test')
-  # We're on Minitest 5+. Nothing to do here.
-else
-  # Minitest 4 doesn't have Minitest::Test yet.
-  Minitest::Test = MiniTest::Unit::TestCase
-end
+require 'minitest/reporters'
+Minitest::Reporters.use! Minitest::Reporters::SpecReporter.new(color: true)
+
+require 'thread'
+require 'thread_safe'
+
+THREADS = (RUBY_ENGINE == 'ruby' ? 100 : 10)
 
 if defined?(JRUBY_VERSION) && ENV['TEST_NO_UNSAFE']
   # to be used like this: rake test TEST_NO_UNSAFE=true

data/thread_safe.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["headius@headius.com", "thedarkone2@gmail.com"]
   gem.description   = %q{Thread-safe collections and utilities for Ruby}
   gem.summary       = %q{A collection of data structures and utilities to make thread-safe programming in Ruby easier}
-  gem.homepage      = "https://github.com/headius/thread_safe"
+  gem.homepage      = "https://github.com/ruby-concurrency/thread_safe"
 
   gem.files         = `git ls-files`.split($\)
   gem.files        += ['lib/thread_safe/jruby_cache_backend.jar'] if defined?(JRUBY_VERSION)
@@ -20,7 +20,7 @@ Gem::Specification.new do |gem|
   gem.version       = ThreadSafe::VERSION
   gem.license       = "Apache-2.0"
 
-  gem.add_development_dependency 'atomic', ['>= 1.1.7', '< 2']
+  gem.add_development_dependency 'atomic', '= 1.1.16'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'minitest', '>= 4'
 end

data/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;
+}
+