active_record_mutex 0.0.0

data/README

@@ -0,0 +1,46 @@
+== Description
+
+This gem provides a Mutex that is based on ctiveRecord's database connection.
+(At the moment this only works for Mysql.) It can be used to synchronise
+different ruby processes via the connected database.
+
+== Download
+
+The latest version of the <b>active_record_mutex</b> source archive can be
+found at
+
+* http://www.ping.de/~flori
+
+== Installation
+
+You can use rubygems to fetch the gem and install it for you:
+
+  # gem install active_record_mutex
+
+You can also put this line into your Rails environment.rb file
+
+  config.gem 'active_record_mutex'
+
+and install the gem via
+
+  $ rake gems:install
+
+== Usage
+
+If you want to synchronize method calls to your model's methods you can easily
+do this by passing a mutex instance to ActiveRecord's synchronize class method.
+This mutex instance will be named Foo like the ActiveRecord was named:
+
+  class Foo < ActiveRecord::Base
+    def foo
+    end
+
+    synchronize :foo, :with => :mutex
+  end
+
+If you want more control over the mutex and/or give it a special name you can
+create Mutex instance like this:
+
+  my_mutex = ActiveRecord::Mutex::Mutex.new(:name => 'my_mutex')
+
+Now you can send all messages directly to the Mutex instance.

data/Rakefile

@@ -0,0 +1,86 @@
+begin
+  require 'rake/gempackagetask'
+rescue LoadError
+end
+require 'rake/clean'
+require 'rbconfig'
+include Config
+
+PKG_NAME         = 'active_record_mutex'
+PKG_VERSION      = File.read('VERSION').chomp
+PKG_FILES        = FileList['**/*'].exclude(/^(doc|CVS|pkg|coverage)/)
+PKG_SUMMARY      = 'Implementation of a Mutex for Active Record'
+PKG_RDOC_OPTIONS = [ '--main', 'README', '--title', PKG_SUMMARY ]
+CLEAN.include 'coverage', 'doc'
+
+desc "Testing library"
+task :test  do
+  ruby %{-Ilib test/mutex_test.rb}
+end
+
+desc "Testing library (with coverage)"
+task :coverage  do
+  sh %{rcov -Ilib test/mutex_test.rb}
+end
+
+desc "Installing library"
+task :install  do
+  ruby 'install.rb'
+end
+
+desc "Creating documentation"
+task :doc do
+  sh 'rdoc', *(PKG_RDOC_OPTIONS + Dir['lib/**/*.rb']  + [ 'README' ])
+end
+
+if defined? Gem
+  spec = Gem::Specification.new do |s|
+    s.name         = PKG_NAME
+    s.version      = PKG_VERSION
+    s.summary      = PKG_SUMMARY
+    s.description  = "Mutex that can be used to synchronise ruby processes via an ActiveRecord"\
+      " datababase connection. (Only Mysql is supported at the moment.)"
+
+    s.files        = PKG_FILES.to_a.sort
+
+    s.require_path = 'lib'
+
+    s.has_rdoc     = true
+    s.rdoc_options = PKG_RDOC_OPTIONS
+    s.extra_rdoc_files << 'README'
+    #s.test_files << 'test/mutex_test.rb'
+
+    s.author            = "Florian Frank"
+    s.email             = "flori@ping.de"
+    s.homepage          = "http://flori.github.com/#{PKG_NAME}"
+    s.rubyforge_project = "#{PKG_NAME}"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar      = true
+    pkg.package_files += PKG_FILES
+  end
+end
+
+desc m = "Writing version information for #{PKG_VERSION}"
+task :version do
+  puts m
+  File.open(File.join('lib', 'active_record', 'mutex', 'version.rb'), 'w') do |v|
+    v.puts <<EOT
+module ActiveRecord
+  module Mutex
+    # ActiveRecord::Mutex version
+    VERSION       = '#{PKG_VERSION}'
+    VERSION_ARRAY = VERSION.split(/\\./).map { |x| x.to_i } # :nodoc:
+    VERSION_MAJOR = VERSION_ARRAY[0] # :nodoc:
+    VERSION_MINOR = VERSION_ARRAY[1] # :nodoc:
+    VERSION_BUILD = VERSION_ARRAY[2] # :nodoc:
+  end
+end
+EOT
+  end
+end
+
+task :default => [ :version, :test ]
+
+task :release => [ :clean, :version, :package ]

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/lib/active_record/mutex.rb

@@ -0,0 +1,148 @@
+require 'active_record'
+require 'active_record/mutex/version'
+
+module ActiveRecord
+  # This module is mixed into ActiveRecord::Base to provide the mutex methods
+  # that return a mutex for a particular ActiveRecord::Base subclass/instance.
+  module Mutex
+    # This is the base exception of all mutex exceptions.
+    class MutexError < ActiveRecordError; end
+
+    # This exception is raised if a mutex of the given name isn't locked at the
+    # moment and unlock was called.
+    class MutexUnlockFailed < MutexError; end
+
+    # This exception is raised if a mutex of the given name is locked at the
+    # moment and lock was called again.
+    class MutexLocked < MutexError; end
+
+    def self.included(modul)
+      modul.instance_eval do
+        extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # Returns a mutex instance for this ActiveRecord subclass.
+      def mutex
+        @mutex ||= Mutex.new(:name => name)
+      end
+    end
+
+    # Returns a mutex instance for this ActiveRecord instance.
+    def mutex
+      @mutex ||= Mutex.new(:name => self.class.name)
+    end
+
+    class Mutex
+      # Creates a mutex with the name given with the option :name.
+      def initialize(opts = {})
+        @name = opts[:name] or raise ArgumentError, "Mutex requires a :name argument"
+      end
+
+      # Returns the name of this mutex as given as a constructor argument.
+      attr_reader :name
+
+      # Locks the mutex if it isn't already locked via another database
+      # connection and yields to the given block. After executing the block's
+      # content the mutex is unlocked (only if it was locked by this
+      # synchronize method before).
+      #
+      # If the mutex was already locked by another database connection the
+      # method blocks until it could aquire the lock and only then the block's
+      # content is executed. If the mutex was already locked by the current database
+      # connection then the block's content is run and the the mutex isn't
+      # unlocked afterwards.
+      #
+      # If a value in seconds is passed to the :timeout option the blocking
+      # ends after that many seconds and the method returns immediately if the
+      # lock couldn't be aquired during that time.
+      def synchronize(opts = {})
+        locked_before = aquired_lock?
+        lock opts
+        yield
+      rescue ActiveRecord::Mutex::MutexLocked
+        return nil
+      ensure
+        locked_before or unlock
+      end
+
+      # Locks the mutex and returns true if successful. If the mutex is
+      # already locked and the timeout in seconds is given as the :timeout
+      # option, this method raises a MutexLocked exception after that many
+      # seconds. If the :timeout option wasn't given, this method blocks until
+      # the lock could be aquired.
+      def lock(opts = {})
+        if opts[:timeout]
+          lock_with_timeout opts
+        else
+          begin
+            lock_with_timeout :timeout => 1
+          rescue MutexLocked
+            retry
+          end
+        end
+      end
+
+      # Unlocks the mutex and returns true if successful. Otherwise this method
+      # raises a MutexLocked exception.
+      def unlock(*)
+        case query("SELECT RELEASE_LOCK(#{ActiveRecord::Base.quote_value(name)})")
+        when 1      then true
+        when 0, nil then raise MutexUnlockFailed, "unlocking of mutex '#{name}' failed"
+        end
+      end
+
+      # Returns true if this mutex is unlocked at the moment.
+      def unlocked?
+        query("SELECT IS_FREE_LOCK(#{ActiveRecord::Base.quote_value(name)})") == 1
+      end
+
+      # Returns true if this mutex is locked at the moment.
+      def locked?
+        not unlocked?
+      end
+ 
+      # Returns true if this mutex is locked by this database connection.
+      def aquired_lock?
+        query("SELECT CONNECTION_ID() = IS_USED_LOCK(#{ActiveRecord::Base.quote_value(name)})") == 1
+      end
+
+      # Returns true if this mutex is not locked by this database connection.
+      def not_aquired_lock?
+        not aquired_lock?
+      end
+
+      # Returns a string representation of this Mutex instance.
+      def to_s
+        "#<#{self.class} #{name}>"
+      end
+
+      alias inspect to_s
+
+      private
+
+      def lock_with_timeout(opts = {})
+        timeout = opts[:timeout] || 1
+        case query("SELECT GET_LOCK(#{ActiveRecord::Base.quote_value(name)}, #{timeout})")
+        when 1 then true
+        when 0 then raise MutexLocked, "mutex '#{name}' is already locked"
+        end
+      end
+
+      def query(sql)
+        if result = ActiveRecord::Base.connection.execute(sql)
+          result = result.fetch_row.first.to_i
+          $DEBUG and warn %{query("#{sql}") = #{result}}
+        end
+        result
+      rescue ActiveRecord::StatementInvalid
+        nil
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include ActiveRecord::Mutex
+end

data/lib/active_record/mutex/version.rb

@@ -0,0 +1,10 @@
+module ActiveRecord
+  module Mutex
+    # ActiveRecord::Mutex version
+    VERSION       = '0.0.0'
+    VERSION_ARRAY = VERSION.split(/\./).map { |x| x.to_i } # :nodoc:
+    VERSION_MAJOR = VERSION_ARRAY[0] # :nodoc:
+    VERSION_MINOR = VERSION_ARRAY[1] # :nodoc:
+    VERSION_BUILD = VERSION_ARRAY[2] # :nodoc:
+  end
+end

data/lib/active_record_mutex.rb

@@ -0,0 +1 @@
+require 'active_record/mutex'

data/test/mutex_test.rb

@@ -0,0 +1,101 @@
+require 'test/unit'
+require 'rubygems'
+
+require 'active_record'
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'active_record/mutex'
+
+ActiveRecord::Base.establish_connection(
+  :adapter  => "mysql",
+  :database => ENV['DATABASE'] || "test",
+  :username => ENV['USER'],
+  :password => ENV['PASSWORD']
+)
+
+class MutexTest < Test::Unit::TestCase
+  class Foo < ActiveRecord::Base; end
+
+  def setup
+    ActiveRecord::Schema.define(:version => 1) do
+      create_table(:foos, :force => true) { |t| t.string :bar }
+    end
+  end
+
+  def teardown
+    ActiveRecord::Base.connection.tables.each do |table|
+      ActiveRecord::Base.connection.drop_table(table)
+    end
+  end
+
+  def test_exported_methods
+    mutex = Foo.mutex
+    assert_kind_of ActiveRecord::Mutex::Mutex, mutex
+    assert_equal mutex.name, Foo.name
+    mutex = Foo.new.mutex
+    assert_kind_of ActiveRecord::Mutex::Mutex, mutex
+    assert_equal mutex.name, Foo.name
+  end
+
+  def test_create
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Create')
+    assert_equal 'Create', mutex.name
+  end
+
+  def test_lock
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Lock')
+    assert mutex.unlocked?
+    assert mutex.lock
+    assert mutex.locked?
+    assert mutex.aquired_lock?
+    assert mutex.lock
+  end
+
+  def test_unlock
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Unlock')
+    assert_raises(ActiveRecord::Mutex::MutexUnlockFailed) { mutex.unlock }
+    assert mutex.lock
+    assert mutex.locked?
+    assert mutex.aquired_lock?
+    assert mutex.unlock
+    assert mutex.unlocked?
+    assert_raises(ActiveRecord::Mutex::MutexUnlockFailed) { mutex.unlock }
+  end
+
+  def test_synchronize
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Sync1')
+    assert mutex.unlocked?
+    mutex.synchronize do
+      assert mutex.locked?
+    end
+    assert mutex.unlocked?
+  end
+
+  def test_synchronize_exception
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Sync2')
+    exception = Class.new StandardError
+    begin
+      assert mutex.unlocked?
+      mutex.synchronize do
+        assert mutex.locked?
+        raise exception
+      end
+    rescue exception
+      assert mutex.unlocked?
+      assert mutex.lock
+      assert mutex.locked?
+    end
+  end
+
+  def test_synchronize_nested
+    mutex = ActiveRecord::Mutex::Mutex.new(:name => 'Sync3')
+    assert mutex.unlocked?
+    mutex.synchronize do
+      assert mutex.locked?
+      mutex.synchronize do
+        assert mutex.locked?
+      end
+      assert mutex.locked?
+    end
+    assert mutex.unlocked?
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: active_record_mutex
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 0
+  version: 0.0.0
+platform: ruby
+authors: 
+- Florian Frank
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-01 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: Mutex that can be used to synchronise ruby processes via an ActiveRecord datababase connection. (Only Mysql is supported at the moment.)
+email: flori@ping.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- CHANGES
+- README
+- Rakefile
+- VERSION
+- lib/active_record/mutex.rb
+- lib/active_record/mutex/version.rb
+- lib/active_record_mutex.rb
+- test/mutex_test.rb
+has_rdoc: true
+homepage: http://flori.github.com/active_record_mutex
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+- --title
+- Implementation of a Mutex for Active Record
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: active_record_mutex
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Implementation of a Mutex for Active Record
+test_files: []
+