atomic 0.0.6-java

data/README.txt

@@ -0,0 +1,33 @@
+atomic: An atomic reference implementation for JRuby and green or GIL-threaded
+Ruby implementations (MRI 1.8/1.9, Rubinius)
+
+== Summary ==
+
+This library provides:
+
+* an Atomic class that guarantees atomic updates to its contained value
+
+The Atomic class provides accessors for the contained "value" plus two update
+methods:
+
+* update will run the provided block, passing the current value and replacing
+  it with the block result iff the value has not been changed in the mean time.
+  It may run the block repeatedly if there are other concurrent updates in
+  progress.
+* try_update will run the provided block, passing the current value and
+  replacing it with the block result. If the value changes before the update
+  can happen, it will throw Atomic::ConcurrentUpdateError.
+
+The atomic repository is at http://github.com/headius/ruby-atomic.
+
+== Usage ==
+
+require 'atomic'
+
+my_atomic = Atomic.new(0)
+my_atomic.update {|v| v + 1}
+begin
+  my_atomic.try_update {|v| v + 1}
+rescue Atomic::ConcurrentUpdateError => cue
+  # deal with it (retry, propagate, etc)
+end

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rake'
+require 'rake/testtask'
+
+task :default => :test
+
+desc "Run tests"
+Rake::TestTask.new :test do |t|
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*.rb"]
+end
+
+desc "Run benchmarks"
+task :bench do
+  exec "ruby -Ilib -Iext test/bench_atomic.rb"
+end
+
+if defined?(JRUBY_VERSION)
+  require 'ant'
+
+  directory "pkg/classes"
+
+  desc "Clean up build artifacts"
+  task :clean do
+    rm_rf "pkg/classes"
+    rm_rf "lib/refqueue.jar"
+  end
+
+  desc "Compile the extension"
+  task :compile => "pkg/classes" do |t|
+    ant.javac :srcdir => "ext", :destdir => t.prerequisites.first,
+      :source => "1.5", :target => "1.5", :debug => true,
+      :classpath => "${java.class.path}:${sun.boot.class.path}"
+  end
+
+  desc "Build the jar"
+  task :jar => :compile do
+    ant.jar :basedir => "pkg/classes", :destfile => "lib/atomic_reference.jar", :includes => "**/*.class"
+  end
+
+  task :package => :jar
+end

data/atomic.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{atomic}
+  s.version = "0.0.6"
+  s.authors = ["Charles Oliver Nutter", "MenTaLguY"]
+  s.date = Time.now.strftime('%Y-%m-%d')
+  s.description = "An atomic reference implementation for JRuby and green or GIL-threaded impls"
+  s.email = ["headius@headius.com", "mental@rydia.net"]
+  s.homepage = "http://github.com/headius/ruby-atomic"
+  s.require_paths = ["lib"]
+  s.summary = "An atomic reference implementation for JRuby and green or GIL-threaded impls"
+  s.test_files = Dir["test/test*.rb"]
+  if defined?(JRUBY_VERSION)
+    s.files = Dir['{lib,examples,test}/**/*'] + Dir['{*.txt,*.gemspec,Rakefile}']
+    s.platform = 'java'
+  else
+    s.files = Dir['{lib,examples,test,ext}/**/*'] + Dir['{*.txt,*.gemspec,Rakefile}']
+    s.extensions = 'ext/extconf.rb'
+  end
+end

data/examples/atomic_example.rb

@@ -0,0 +1,12 @@
+require 'atomic'
+
+my_atomic = Atomic.new(0)
+my_atomic.update {|v| v + 1}
+puts "new value: #{my_atomic.value}"
+
+begin
+  my_atomic.try_update {|v| v + 1}
+rescue Atomic::ConcurrentUpdateError => cue
+  # deal with it (retry, propagate, etc)
+end
+puts "new value: #{my_atomic.value}"

data/examples/bench_atomic.rb

@@ -0,0 +1,109 @@
+require 'benchmark'
+require 'atomic'
+require 'thread'
+Thread.abort_on_exception = true
+
+$go = false # for synchronizing parallel threads
+
+# number of updates on the value
+N = ARGV[1] ? ARGV[1].to_i : 100_000
+
+# number of threads for parallel test
+M = ARGV[0] ? ARGV[0].to_i : 100
+
+
+puts "*** Sequential updates ***"
+Benchmark.bm(10) do |x|
+  value = 0
+  x.report "no lock" do
+    N.times do
+      value += 1
+    end
+  end
+
+  @lock = Mutex.new
+  x.report "mutex" do
+    value = 0
+    N.times do
+      @lock.synchronize do
+        value += 1
+      end
+    end
+  end
+
+  @atom = Atomic.new(0)
+  x.report "atomic" do
+    N.times do
+      @atom.update{|x| x += 1}
+    end
+  end
+end
+
+def para_setup(num_threads, count, &block)
+  if num_threads % 2 > 0
+    raise ArgumentError, "num_threads must be a multiple of two"
+  end
+  raise ArgumentError, "need block" unless block_given?
+
+  # Keep those threads together
+  tg = ThreadGroup.new
+
+  num_threads.times do |i|
+    diff = (i % 2 == 0) ? 1 : -1
+
+    t = Thread.new do
+      nil until $go
+      count.times do
+        yield diff
+      end
+    end
+
+    tg.add(t)
+  end
+
+  # Make sure all threads are started
+  while tg.list.find{|t| t.status != "run"}
+    Thread.pass
+  end
+
+  # For good measure
+  GC.start
+
+  tg
+end
+
+def para_run(tg)
+  $go = true
+  tg.list.each{|t| t.join}
+  $go = false
+end
+
+puts "*** Parallel updates ***"
+Benchmark.bm(10) do |bm|
+  # This is not secure
+  value = 0
+  tg = para_setup(M, N/M) do |diff|
+    value += diff
+  end
+  bm.report("no lock"){ para_run(tg) }
+
+
+  value = 0
+  @lock = Mutex.new
+  tg = para_setup(M, N/M) do |diff|
+    @lock.synchronize do
+      value += diff
+    end
+  end
+  bm.report("mutex"){ para_run(tg) }
+  raise unless value == 0
+
+
+  @atom = Atomic.new(0)
+  tg = para_setup(M, N/M) do |diff|
+    @atom.update{|x| x + diff}
+  end
+  bm.report("atomic"){ para_run(tg) }
+  raise unless @atom.value == 0
+
+end

data/lib/atomic.rb

@@ -0,0 +1,94 @@
+require 'thread'
+
+class Atomic
+  class ConcurrentUpdateError < ThreadError
+  end
+  
+  def initialize(value=nil)
+    @ref = InternalReference.new(value)
+  end
+
+  def value
+    @ref.get
+  end
+  alias get value
+  
+  def value=(new_value)
+    @ref.set(new_value)
+    new_value
+  end
+  alias set value=
+
+  def swap(new_value)
+    @ref.get_and_set(new_value)
+  end
+  alias get_and_set swap
+  
+  def compare_and_swap(old_value, new_value)
+    @ref.compare_and_set(old_value, new_value)
+  end
+  alias compare_and_set compare_and_swap
+
+  # 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.
+  def update
+    true until @ref.compare_and_set(old_value = @ref.get, new_value = yield(old_value))
+    new_value
+  end
+  
+  # frozen pre-allocated backtrace to speed ConcurrentUpdateError
+  CONC_UP_ERR_BACKTRACE = ['backtrace elided; set verbose to enable'].freeze
+
+  def try_update
+    old_value = @ref.get
+    new_value = yield old_value
+    unless @ref.compare_and_set(old_value, new_value)
+      if $VERBOSE
+        raise ConcurrentUpdateError, "Update failed"
+      else
+        raise ConcurrentUpdateError, "Update failed", CONC_UP_ERR_BACKTRACE
+      end
+    end
+    new_value
+  end
+end
+
+begin
+  require 'atomic_reference'
+rescue LoadError
+  # Portable/generic (but not very memory or scheduling-efficient) fallback
+  class Atomic::InternalReference #:nodoc: all
+    def initialize(value)
+      @mutex = Mutex.new
+      @value = value
+    end
+
+    def get
+      @mutex.synchronize { @value }
+    end
+
+    def set(new_value)
+      @mutex.synchronize { @value = new_value }
+    end
+
+    def get_and_set(new_value)
+      @mutex.synchronize do
+        old_value = @value
+        @value = new_value
+        old_value
+      end
+    end
+
+    def compare_and_set(old_value, new_value)
+      return false unless @mutex.try_lock
+      begin
+        return false unless @value.equal? old_value
+        @value = new_value
+      ensure
+        @mutex.unlock
+      end
+      true
+    end
+  end
+end

data/test/test_atomic.rb

@@ -0,0 +1,63 @@
+require 'test/unit'
+require 'atomic'
+
+class TestAtomic < Test::Unit::TestCase
+  def test_construct
+    atomic = Atomic.new
+    assert_equal nil, atomic.value
+    
+    atomic = Atomic.new(0)
+    assert_equal 0, atomic.value
+  end
+  
+  def test_value
+    atomic = Atomic.new(0)
+    atomic.value = 1
+    
+    assert_equal 1, atomic.value
+  end
+  
+  def test_update
+    # use a number outside JRuby's fixnum cache range, to ensure identity is preserved
+    atomic = Atomic.new(1000)
+    res = atomic.update {|v| v + 1}
+    
+    assert_equal 1001, atomic.value
+    assert_equal 1001, res
+  end
+  
+  def test_try_update
+    # use a number outside JRuby's fixnum cache range, to ensure identity is preserved
+    atomic = Atomic.new(1000)
+    res = atomic.try_update {|v| v + 1}
+    
+    assert_equal 1001, atomic.value
+    assert_equal 1001, res
+  end
+
+  def test_swap
+    atomic = Atomic.new(1000)
+    res = atomic.swap(1001)
+
+    assert_equal 1001, atomic.value
+    assert_equal 1000, res
+  end
+  
+  def test_try_update_fails
+    # use a number outside JRuby's fixnum cache range, to ensure identity is preserved
+    atomic = Atomic.new(1000)
+    assert_raise Atomic::ConcurrentUpdateError do
+      # assigning within block exploits implementation detail for test
+      atomic.try_update{|v| atomic.value = 1001 ; v + 1}
+    end
+  end
+
+  def test_update_retries
+    tries = 0
+    # use a number outside JRuby's fixnum cache range, to ensure identity is preserved
+    atomic = Atomic.new(1000)
+    # assigning within block exploits implementation detail for test
+    atomic.update{|v| tries += 1 ; atomic.value = 1001 ; v + 1}
+    assert_equal 2, tries
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: atomic
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.6
+platform: java
+authors: 
+  - Charles Oliver Nutter
+  - MenTaLguY
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-06 00:00:00 Z
+dependencies: []
+
+description: An atomic reference implementation for JRuby and green or GIL-threaded impls
+email: 
+  - headius@headius.com
+  - mental@rydia.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+  - lib/atomic.rb
+  - lib/atomic_reference.jar
+  - examples/atomic_example.rb
+  - examples/bench_atomic.rb
+  - test/test_atomic.rb
+  - README.txt
+  - atomic.gemspec
+  - Rakefile
+homepage: http://github.com/headius/ruby-atomic
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.9
+signing_key: 
+specification_version: 3
+summary: An atomic reference implementation for JRuby and green or GIL-threaded impls
+test_files: 
+  - test/test_atomic.rb