distributed_mutex 1.0.0

data/.gitignore

@@ -0,0 +1 @@
+spec/config/database.yml

data/README.rdoc

@@ -0,0 +1,25 @@
+= distributed_mutex
+
+by Birkir A. Barkarson <birkirb@stoicviking.net>
+
+== Description
+
+A rails plugin proving an abstract distributed mutex along with a MySQL implementation that uses
+mysql named locks. Others distributed locks using Memcached etc could be implemented using the same
+framework.
+
+== Installation from source
+
+  git clone git://github.com/birkirb/distributed_mutex.git
+  cd distributed_mutex
+  rake install
+
+=== Rails Plugin Installation
+
+  script/plugin install git://github.com/birkirb/distributed_mutex.git
+
+== Copyright
+
+Author::    Birkir A. Barkarson <birkirb@stoicviking.net>
+Copyright:: Copyright (c) 2009
+License::   MIT License

data/Rakefile

@@ -0,0 +1,134 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = %q{distributed_mutex}
+    s.authors = ["Birkir A. Barkarson"]
+    s.description = %q{Framework for using a distributed mutex. Implementation of a mutex stored on a MySQL database.}
+    s.summary = s.description
+    s.email = %q{birkirb@stoicviking.net}
+    s.has_rdoc = true
+    s.homepage = %q{http://github.com/birkirb/distributed_mutex}
+    #s.rubyforge_project = %q{serializable}
+    #s.rubygems_version = %q{1.3.1}
+    #s.required_rubygems_version = "1.3.1"
+    s.add_dependency(%q<activerecord>, [">= 1.2"])
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+begin
+  require 'spec/rake/spectask'
+
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_opts = ["-f specdoc", "-c"]
+    t.spec_files = FileList['spec/*_spec.rb']
+  end
+
+rescue LoadError
+  desc 'Spec rake task not available'
+  task :spec do
+    abort 'Spec rake task is not available. Be sure to install rspec as a gem or plugin'
+  end
+end
+
+# begin
+#   require 'cucumber'
+#   require 'cucumber/rake/task'
+
+
+#   desc "Run Cucumber feature tests"
+#   Cucumber::Rake::Task.new(:features) do |t|
+#     t.cucumber_opts = "--format pretty" 
+#   end
+
+# rescue LoadError
+#   desc 'Cucumber rake task not available'
+#   task :features do
+#     abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
+#   end
+# end
+
+begin
+  require 'spec/rake/spectask'
+# require 'cucumber'
+# require 'cucumber/rake/task'
+  require 'spec/rake/verify_rcov'
+
+  task :test do
+    Rake::Task[:spec].invoke
+#   Rake::Task[:features].invoke
+  end
+
+  desc "Run tests with RCov"
+  namespace :rcov do
+    rm "coverage.data" if File.exist?("coverage.data")
+
+#   desc "Run Features with RCov"
+#   Cucumber::Rake::Task.new(:features) do |t|
+#     t.rcov = true
+#     t.rcov_opts = %w{ --exclude osx\/objc,gems\/,spec\/,features\/ --aggregate coverage.data}
+#     t.rcov_opts << %[-o "coverage"]
+#   end
+
+    Spec::Rake::SpecTask.new(:spec) do |t|
+      t.spec_opts = ["-f specdoc", "-c"]
+      t.spec_files = FileList['spec/*_spec.rb']
+      t.rcov = true
+      t.rcov_opts = %w{--exclude "spec/*,gems/*,features/*" --aggregate "coverage.data"}
+    end
+
+    desc "Run both specs and features to generate aggregated coverage"
+    task :all do |t|
+      Rake::Task["rcov:spec"].invoke
+#     Rake::Task["rcov:features"].invoke
+    end
+
+    RCov::VerifyTask.new(:verify => 'rcov:all') do |t|
+      t.threshold = 93.98
+      t.index_html = 'coverage/index.html'
+    end
+  end
+rescue LoadError
+  desc 'Rcov rake task not available'
+  task :rcov do
+    abort 'rcov rake task is not available. Be sure to install rspec, rcov and cucumber as a gem or plugin'
+  end
+end
+
+begin
+  require 'metric_fu'
+
+  MetricFu::Configuration.run do |config|
+    #define which metrics you want to use
+    config.metrics  = [:churn, :flog, :flay, :reek, :roodi]
+    config.flay     = { :dirs_to_flay => ['app', 'lib']  } 
+    config.flog     = { :dirs_to_flog => ['app', 'lib']  }
+    config.reek     = { :dirs_to_reek => ['app', 'lib']  }
+    config.roodi    = { :dirs_to_roodi => ['app', 'lib'] }
+    config.saikuro  = { :output_directory => 'scratch_directory/saikuro', 
+      :input_directory => ['app', 'lib'],
+      :cyclo => "",
+      :filter_cyclo => "0",
+      :warn_cyclo => "5",
+      :error_cyclo => "7",
+      :formater => "text"} #this needs to be set to "text"
+    config.churn    = { :start_date => "1 year ago", :minimum_churn_count => 10}
+    config.rcov     = { :test_files => ['test/**/*_test.rb', 
+      'spec/**/*_spec.rb'],
+      :rcov_opts => ["--sort coverage", 
+        "--no-html", 
+        "--text-coverage",
+        "--no-color",
+        "--profile",
+        "--rails",
+        "--exclude /gems/,/Library/,spec"]}
+  end
+
+rescue LoadError
+  # Too bad
+end
+
+task :default => [:spec]

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/init.rb

@@ -0,0 +1 @@
+require 'mysql_mutex'

data/lib/distributed_mutex.rb

@@ -0,0 +1,88 @@
+require 'mutex_lock_timeout'
+
+class DistributedMutex < Mutex
+
+  DEFAULT_TIMEOUT = 1
+  DEFAULT_EXCEPTION_ON_TIMEOUT = false
+
+  attr_reader :key, :timeout, :exception_on_timeout
+  alias excluse_unlock unlock
+
+  def initialize(key, timeout = DEFAULT_TIMEOUT, exception_on_timeout = DEFAULT_EXCEPTION_ON_TIMEOUT)
+    @key = key
+    @timeout = timeout
+    @locked = false
+    @exception_on_timeout = exception_on_timeout
+  end
+
+  def lock
+    if @locked = get_lock
+      true
+    else
+      if @exception_on_timeout
+        raise MutexLockTimeout.new
+      else
+        false
+      end
+    end
+  end
+
+  def locked?
+    @locked
+  end
+
+  def synchronize(&block)
+    if self.lock
+      begin
+        yield
+      ensure
+        self.unlock
+      end
+      true
+    else
+      false
+    end
+  end
+
+  def try_lock
+    was_locked = nil
+    begin
+      self.lock
+      was_locked = locked?
+    ensure
+      self.unlock
+    end
+    was_locked
+  end
+
+  def unlock
+    if @locked
+      if release_lock
+        @locked = false
+        true
+      else
+        false
+      end
+    else
+      false
+    end
+  end
+
+  def self.synchronize(key, timeout = DEFAULT_TIMEOUT, exception_on_timeout = DEFAULT_EXCEPTION_ON_TIMEOUT, &block)
+    mutex = new(key, timeout, exception_on_timeout)
+    mutex.synchronize(&block)
+  end
+
+  private
+
+  # Return true if and only if a lock is obtained
+  def get_lock
+    raise 'Method not implemented'
+  end
+
+  # Return true if and only if a lock is released
+  def release_lock
+    raise 'Method not implemented'
+  end
+
+end

data/lib/global_mutex.rb

@@ -0,0 +1,36 @@
+require 'distributed_mutex'
+
+# Simple global variable mutex, not production quality more
+# as a test implementation for the super class.
+class GlobalMutex < DistributedMutex
+
+  private
+
+  def get_lock
+    if @timeout && @timeout > 1
+      1.upto(@timeout) do
+        if set_global_mutex
+          return true
+        else
+          sleep(1)
+        end
+      end
+    end
+    return set_global_mutex
+  end
+
+  def release_lock
+    eval("$#{@key} = nil")
+    true
+  end
+
+  def set_global_mutex
+    if nil == eval("$#{@key}")
+      eval("$#{@key} = 1")
+      true
+    else
+      false
+    end
+  end
+
+end

data/lib/mutex_lock_timeout.rb

@@ -0,0 +1,6 @@
+class MutexLockTimeout < StandardError
+
+  def message
+    'Mutex lock operation timed out'
+  end
+end

data/lib/mysql_mutex.rb

@@ -0,0 +1,35 @@
+require 'active_record'
+require 'distributed_mutex'
+
+class MySQLMutex < DistributedMutex
+
+  def initialize(key, timeout = DEFAULT_TIMEOUT, exception_on_timeout = DEFAULT_EXCEPTION_ON_TIMEOUT, connection = ActiveRecord::Base.connection)
+    @connection = connection
+    @lock_was_free = false
+    @get_sql = ActiveRecord::Base.send(:sanitize_sql_array,["SELECT IS_FREE_LOCK(?), GET_LOCK(?,?)", key, key, timeout])
+    @release_sql = ActiveRecord::Base.send(:sanitize_sql_array,["SELECT RELEASE_LOCK(?)", key])
+    super(key, timeout, exception_on_timeout)
+  end
+
+  def self.synchronize(key, timeout = DEFAULT_TIMEOUT, exception_on_timeout = DEFAULT_TIMEOUT, con = ActiveRecord::Base.connection, &block)
+    mutex = new(key, timeout, exception_on_timeout, con)
+    mutex.synchronize(&block)
+  end
+
+  private
+
+  def get_lock
+    is_free_lock, get_lock = @connection.select_rows(@get_sql).first
+    @lock_was_free = ('1' == is_free_lock)
+    '1' == get_lock
+  end
+
+  def release_lock
+    if @lock_was_free
+      '1' == @connection.select_value(@release_sql)
+    else
+      true
+    end
+  end
+
+end

data/spec/config/database.stub

@@ -0,0 +1,10 @@
+development: &defaults
+  adapter: mysql
+  database: mysql
+  username:
+  password:
+  host: localhost
+  encoding: utf8
+
+test:
+  <<: *defaults

data/spec/global_mutex_spec.rb

@@ -0,0 +1,130 @@
+require 'spec/spec_helper'
+require 'global_mutex'
+
+describe GlobalMutex, 'when created with a key and timeout' do
+
+  it 'should give access to the key and timeout values' do
+    mutex = GlobalMutex.new('test', 1)
+    mutex.timeout.should == 1
+    mutex.key.should == 'test'
+  end
+
+  it 'should allow querying on lock state' do
+    mutex = GlobalMutex.new('test', 1)
+    mutex.locked?.should == false
+  end
+
+  it 'should allow locking and unlocking and report the success or failure of these operations' do
+    mutex = GlobalMutex.new('test', 1)
+    mutex.lock.should == true
+    mutex.locked?.should == true
+
+    mutex_2 = GlobalMutex.new('test', 0)
+    mutex_2.locked?.should == false
+    mutex_2.lock.should == false
+    mutex_2.locked?.should == false
+    mutex_2.unlock.should == false
+
+    mutex.unlock.should == true
+    mutex.locked?.should == false
+
+    mutex_2.lock.should == true
+    mutex_2.locked?.should == true
+    mutex.locked?.should == false
+    mutex_2.unlock.should == true
+    mutex_2.locked?.should == false
+  end
+
+  it 'should allow lock attempts and report the success or failure of the operation' do
+    mutex = GlobalMutex.new('test', 1)
+    mutex.try_lock.should == true
+    mutex.locked?.should == false
+  end
+
+  it 'should allow locked operations in a block via #synchronize' do
+    block_assigned_variable = 0
+
+    mutex = GlobalMutex.new('test', 1)
+    mutex.locked?.should == false
+    success = mutex.synchronize do
+      block_assigned_variable = 1
+      mutex.locked?.should == true
+    end
+    success.should == true
+    mutex.locked?.should == false
+    block_assigned_variable.should == 1
+  end
+
+  it 'should report failed block operationds via #synchronize' do
+    block_assigned_variable = 0
+
+    mutex_locked = GlobalMutex.new('test', 1)
+    mutex_locked.lock
+    mutex_locked.locked?.should == true
+
+    mutex = GlobalMutex.new('test', 1)
+    mutex.locked?.should == false
+    success = mutex.synchronize do
+      block_assigned_variable = 1
+    end
+
+    success.should == false
+    mutex.locked?.should == false
+    block_assigned_variable.should == 0
+    mutex_locked.unlock.should == true
+  end
+
+  it 'should pass up error in synchronize' do
+    mutex = GlobalMutex.new('test', 1)
+    lambda do
+      mutex.synchronize do
+        raise 'some_error'
+      end
+    end.should raise_error('some_error')
+    mutex.locked?.should == false
+  end
+
+  it 'should wait until the timeout passes before giving up' do
+    mutex_locked = GlobalMutex.new('test', 1)
+    mutex_locked.lock
+
+    time_start = Time.now
+    mutex = GlobalMutex.new('test', 3)
+    mutex.lock.should == false
+    time_end = Time.now
+    (time_end - time_start + 0.05).should > 3
+
+    mutex_locked.unlock.should == true
+
+    mutex = GlobalMutex.new('test', 3)
+    mutex.lock.should == true
+    mutex.unlock.should == true
+  end
+
+  it 'should throw an exception when so enabled on mutex timeout' do
+    mutex_locked = GlobalMutex.new('test', 1)
+    mutex_locked.lock
+
+    mutex = GlobalMutex.new('test', 0, true)
+    lambda { mutex.lock }.should raise_error(MutexLockTimeout, 'Mutex lock operation timed out')
+    mutex.locked?.should == false
+    mutex_locked.unlock.should == true
+  end
+
+end
+
+describe GlobalMutex, 'when access via a class synchronized method' do
+
+  it 'should use key and time values for direct access to the #synchronize' do
+    block_assigned_variable = 0
+
+    success = GlobalMutex.synchronize('test', 1) do
+      GlobalMutex.new('test', 0).try_lock.should == false
+      block_assigned_variable = 1
+    end
+    success.should == true
+    block_assigned_variable.should == 1
+    GlobalMutex.new('test', 0).try_lock.should == true
+  end
+
+end

data/spec/mysql_mutex_spec.rb

@@ -0,0 +1,136 @@
+require 'spec/spec_helper'
+require 'mysql_mutex'
+
+describe MySQLMutex, 'with a lock on an open mysql connection' do
+
+  before(:all) do
+    ActiveRecord::Base.configurations = database_config
+  end
+
+  before(:each) do
+    $output = ""
+  end
+
+  it 'should work with a synchronized block in one thread' do
+    thread_1 = Thread.new do
+      ActiveRecord::Base.establish_connection(:test)
+      MySQLMutex.synchronize('test', 1) do
+        $output += "1\n"
+      end
+    end
+    thread_1.join
+    $output.should == "1\n"
+  end
+
+  it 'should work with multible threads' do
+    $output = Array.new
+    threads = Array.new
+    1.upto(3) do |number|
+      threads << Thread.new(number) do |number|
+        con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+        MySQLMutex.synchronize('test', 5, con) do
+          $output << number
+        end
+      end
+    end
+
+    threads.each { |t| t.join }
+
+    $output.sort.should == [1, 2, 3]
+  end
+
+  it 'should work with two excluding threads' do
+    thread_1_mutex = nil
+    thread_1 = Thread.new do
+      con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+      thread_1_mutex = MySQLMutex.new('test', 1, false, con)
+      $output += "1-RUN"
+      $output += "-LOCK" if thread_1_mutex.lock
+    end
+
+    thread_1.join
+
+    thread_2 = Thread.new do
+      con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+      mutex = MySQLMutex.new('test', 1, false, con)
+      $output += "-2-RUN"
+      $output += "-LOCK" if mutex.lock
+    end
+
+    thread_2.join
+    $output.should == "1-RUN-LOCK-2-RUN"
+    thread_1_mutex.unlock.should == true
+  end
+
+  it 'should not be released by a nested lock on the same connection' do
+    thread_1_mutex = nil
+    thread_2_mutex = nil
+
+    con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+    thread_1_mutex_1 = MySQLMutex.new('test', 1, false, con)
+
+    thread_1_mutex_1.lock.should == true
+
+    thread_1_mutex_2 = MySQLMutex.new('test', 1, false, con)
+
+    thread_1_mutex_2.lock.should == true
+    thread_1_mutex_2.unlock.should == true
+
+    thread_2 = Thread.new do
+      con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+      thread_2_mutex = MySQLMutex.new('test', 1, false, con)
+      thread_2_mutex.lock.should == false # Should still be locked.
+    end
+
+    thread_2.join
+    thread_1_mutex_1.unlock.should == true
+  end
+
+  it 'should not be released by a nested synchronized lock on the same connection' do
+    con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+    sub_thread_executed = false
+    MySQLMutex.synchronize('test', 1, true, con) do
+      MySQLMutex.synchronize('test', 1, false, con) do
+        sub_thread_executed = true
+      end
+
+      thread_2 = Thread.new do
+        con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+        MySQLMutex.synchronize('test', 1, false, con) do
+          fail
+        end
+      end
+      thread_2.join
+    end
+
+    sub_thread_executed.should == true
+  end
+
+  it 'should released nested synchronized locks when an error occurs' do
+    con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+    sub_thread_executed = false
+    begin
+        lambda do
+          MySQLMutex.synchronize('test', 1, true, con) do
+            MySQLMutex.synchronize('test', 1, false, con) do
+              raise 'TestError'
+              fail
+            end
+            fail
+          end
+        end.should raise_error(RuntimeError, 'TestError')
+
+        thread_2 = Thread.new do
+          con = ActiveRecord::Base.mysql_connection(ActiveRecord::Base.configurations['test'])
+          MySQLMutex.synchronize('test', 1, false, con) do
+            sub_thread_executed = true
+          end
+        end
+        thread_2.join
+    rescue => err
+      fail(err)
+    end
+
+    sub_thread_executed.should == true
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'spec'
+
+$:.unshift "#{File.dirname(__FILE__)}/../lib"
+
+def database_config
+  YAML.load_file('spec/config/database.yml')
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: distributed_mutex
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Birkir A. Barkarson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-05 00:00:00 +09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        version: "1.2"
+  type: :runtime
+  version_requirements: *id001
+description: Framework for using a distributed mutex. Implementation of a mutex stored on a MySQL database.
+email: birkirb@stoicviking.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- lib/distributed_mutex.rb
+- lib/global_mutex.rb
+- lib/mutex_lock_timeout.rb
+- lib/mysql_mutex.rb
+- spec/config/database.stub
+- spec/global_mutex_spec.rb
+- spec/mysql_mutex_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/birkirb/distributed_mutex
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Framework for using a distributed mutex. Implementation of a mutex stored on a MySQL database.
+test_files: 
+- spec/spec_helper.rb
+- spec/mysql_mutex_spec.rb
+- spec/global_mutex_spec.rb