fatalistic 0.0.1

data/.gitignore

@@ -0,0 +1,12 @@
+Gemfile
+Gemfile.lock
+doc
+docs
+pkg
+.DS_Store
+coverage
+.yardoc
+*.gem
+*.sqlite3
+*.rbc
+*.lock

data/README.md

@@ -0,0 +1,96 @@
+# Fatalistic
+
+Fatalistic is a Ruby gem that adds table-level locking to Active Record.
+
+## Table locks
+
+Table-level locks can be used to restrict read and write access to a table.
+Neither Postgres nor MySQL currently support truly serializabile transactions,
+so table locks are sometimes necessary to reliably avoid the "phantom record"
+problem. See this [Wikipedia
+article](http://en.wikipedia.org/wiki/Isolation_\(database_systems\)#Isolation_Levels.2C_Read_Phenomena_and_Locks)
+for more details.
+
+The [MySQL
+docs](http://dev.mysql.com/doc/refman/5.1/en/lock-tables-restrictions.html) show
+a classic usage scenario for table locking:
+
+    LOCK TABLES trans READ, customer WRITE;
+    SELECT SUM(value) FROM trans WHERE customer_id=some_id;
+    UPDATE customer
+      SET total_value=sum_from_previous_statement
+      WHERE customer_id=some_id;
+    UNLOCK TABLES;
+
+
+Table-level locks are generally best avoided when possible because of their
+potential impact on performance. MySQL/Innodb's locking implementation is also
+clunky and fraught with bizarre behaviors, [particularly when used with
+transactions](http://dev.mysql.com/doc/refman/5.1/en/lock-tables-and-transactions.html).
+Before relying on table locks, see if there's some other way to accomplish your
+goal. However, they can be useful when used sparingly.
+
+## Doesn't Active Record already support locking?
+
+Active Record supports row-level locking, but not table locking.
+
+If you do something like `Person.lock` with Active Record will emit the query
+`SELECT * FROM people FOR UPDATE`. This is bad for performance because if you
+have a lot of rows, it's going to be very slow. It's also nearly useless,
+because it still doesn't prevent new records from being inserted. Finally, it's
+foolish because if you want to lock every row in a table, it makes much more
+sense to lock the table itself.
+
+Active Record comes with 2 locking modules: optimistic and pessimistic. Since
+this locking mode is the most "extreme" of the three, I've named it
+"fatalistic."
+
+## What Fatalistic does
+
+MySQL and Postgres use the same row locking syntax, but quite different table
+locking syntax. This library provides the abstraction needed to use them both
+with Active Record. SQLite does not support table level locking, so the methods
+provided here are just no-ops with SQLite.
+
+Fatalistic changes the behavior of the top-level `lock` method so that
+`Person.lock` will lock the entire table, but `Person.where(...).lock` will
+continue to lock just the selected records.
+
+## Example
+
+    class Person < ActiveRecord::Base
+    end
+
+    Person.lock do
+      # your code here
+    end
+
+
+## Getting it
+
+Just install with RubyGems:
+
+    gem install fatalistic
+
+The source code is [on Github](https://github.com/bvision/fatalistic).
+
+## License
+
+Copyright (c) 2011-2012 Norman Clarke and Business Vision SA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+require "rake/testtask"
+
+task :default => :test
+
+Rake::TestTask.new {|t| t.test_files = ['test/test.rb']}
+
+task :clean do
+  sh "rm -rf *.gem doc pkg coverage `find . -name '*.rbc'`"
+end
+
+task :gem do
+  sh "gem build fatalistic.gemspec"
+end

data/fatalistic.gemspec

@@ -0,0 +1,20 @@
+require File.expand_path("../lib/fatalistic", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name              = "fatalistic"
+  s.version           = Fatalistic::VERSION
+  s.authors           = ["Norman Clarke"]
+  s.email             = ["norman@njclarke.com"]
+  s.homepage          = "http://github.com/bvision/fatalistic"
+  s.summary           = "Table-level locking for Active Record"
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- {test}/*`.split("\n")
+  s.require_paths     = ["lib"]
+
+  s.add_development_dependency "minitest"
+
+  s.description = <<-EOM
+Active Record provides "optimistic" and "pessimistic" modules for row-level
+locking, but provide nothing to do full-table locking. Fatalistic provides this.
+EOM
+end

data/lib/active_record/locking/fatalistic.rb

@@ -0,0 +1,37 @@
+require "active_record"
+require "fatalistic"
+
+module ActiveRecord
+  module Locking
+    module Fatalistic
+      # Performs a table-level lock. If this method is invoked with a block,
+      # then a new transaction is begun, and the table is locked inside the
+      # transaction. If invoked without a block, then it simple emits the
+      # appropriate +LOCK TABLE+ statement.
+      def lock(lock_statement = nil, &block)
+        locker = ::Fatalistic::Locker.for(self)
+        if block_given?
+          transaction do
+            begin
+              locker.lock(lock_statement)
+              yield
+            ensure
+              locker.unlock
+            end
+          end
+        else
+          locker.lock(lock_statement)
+        end
+      end
+
+      # Unlock the table. This is only needed by MySQL. If you called +lock+
+      # with a block, then this is invoked for you automatically.
+      def unlock
+        ::Fatalistic::Locker.for(self).unlock
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.method(:lock).owner.send :remove_method, :lock
+ActiveRecord::Base.extend ActiveRecord::Locking::Fatalistic

data/lib/fatalistic.rb

@@ -0,0 +1,66 @@
+require "forwardable"
+
+# Table locking for Active Record.
+module Fatalistic
+
+  VERSION = "0.0.1"
+
+  # This class provides syntax abstraction for table locking. If this
+  # functionality is ever added to Active Record, the final code will end up
+  # looking much different: it's currently set up with as much functionality
+  # outside AR as possible, in order to simplify testing and reduce
+  # dependencies.
+  class Locker
+    extend Forwardable
+    attr :model_class
+    def_delegators :model_class, :connection, :quoted_table_name
+
+    # Factory method to get an instance of the appropriate Locker subclass.
+    def self.for(model_class)
+      adapter_name = model_class.connection.adapter_name.downcase
+      klass = if adapter_name.index("post")
+        PostgresLocker
+      elsif adapter_name.index("my")
+        MySQLLocker
+      else
+        self
+      end
+      klass.new(model_class)
+    end
+
+    def initialize(model_class)
+      @model_class = model_class
+    end
+
+    # Lock the table.
+    def lock(lock_statement = nil)
+    end
+
+    # Unlock the table. This is a no-op on all databases other than MySQL.
+    def unlock
+    end
+  end
+
+  # Table locking for Postgres.
+  class PostgresLocker < Locker
+    def lock(lock_statement = nil)
+      stmt = "LOCK TABLE #{quoted_table_name}"
+      stmt.insert(-1, " #{lock_statement}") if lock_statement
+      connection.execute(stmt)
+    end
+  end
+
+  # Table locking for MySQL.
+  class MySQLLocker < Locker
+    def lock(lock_statement = nil)
+      stmt = "LOCK TABLES #{quoted_table_name}"
+      lock_statement ||= "WRITE"
+      stmt.insert(-1, " #{lock_statement}")
+      connection.execute(stmt)
+    end
+
+    def unlock
+      connection.execute("UNLOCK TABLES")
+    end
+  end
+end

data/test/test.rb

@@ -0,0 +1,72 @@
+require "rubygems"
+
+$LOAD_PATH << File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.uniq!
+
+require "minitest/spec"
+require "minitest/autorun"
+require "fatalistic"
+
+class MockModel
+  attr_accessor :connection
+
+  def quoted_table_name
+    "dummy_table"
+  end
+end
+
+describe Fatalistic::PostgresLocker do
+
+  describe "#lock" do
+
+    before do
+      @model = MockModel.new
+      @model.connection = MiniTest::Mock.new
+      @locker = Fatalistic::PostgresLocker.new(@model)
+    end
+
+    it "should execute a default lock statement" do
+      @model.connection.expect :execute, 'LOCK TABLE "dummy_table"', [String]
+      @locker.lock
+      assert @model.connection.verify
+    end
+
+    it "should execute a modified lock statement" do
+      @model.connection.expect :execute, 'LOCK TABLE "dummy_table" foo', [String]
+      @locker.lock "foo"
+      assert @model.connection.verify
+    end
+  end
+
+end
+
+describe Fatalistic::MySQLLocker do
+
+  before do
+    @model = MockModel.new
+    @model.connection = MiniTest::Mock.new
+    @locker = Fatalistic::MySQLLocker.new(@model)
+  end
+
+  describe "#lock" do
+    it "should execute a default lock statement" do
+      @model.connection.expect :execute, 'LOCK TABLES "dummy_table" WRITE', [String]
+      @locker.lock
+      assert @model.connection.verify
+    end
+
+    it "should execute a modified lock statement" do
+      @model.connection.expect :execute, 'LOCK TABLES "dummy_table" foo', [String]
+      @locker.lock "foo"
+      assert @model.connection.verify
+    end
+  end
+
+  describe "#unlock" do
+    it "should execute an unlock statement" do
+      @model.connection.expect :execute, 'UNLOCK TABLES', [String]
+      @locker.unlock
+      assert @model.connection.verify
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: fatalistic
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Norman Clarke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70320304314940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70320304314940
+description: ! 'Active Record provides "optimistic" and "pessimistic" modules for
+  row-level
+
+  locking, but provide nothing to do full-table locking. Fatalistic provides this.
+
+'
+email:
+- norman@njclarke.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- README.md
+- Rakefile
+- fatalistic.gemspec
+- lib/active_record/locking/fatalistic.rb
+- lib/fatalistic.rb
+- test/test.rb
+homepage: http://github.com/bvision/fatalistic
+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.10
+signing_key: 
+specification_version: 3
+summary: Table-level locking for Active Record
+test_files: []
+has_rdoc: