r4664@asus: jeremy | 2006-06-19 18:55:36 -0700

Use the #lock method to obtain a row lock on a single record. Simply reloads the record with :lock => true.


git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4462 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

@@ -1,6 +1,6 @@
 *SVN*
 
-* Row locking. Provide a locking clause with the :lock finder option or true for the default "FOR UPDATE". [Shugo Maeda]
+* Row locking. Provide a locking clause with the :lock finder option or true for the default "FOR UPDATE". Use the #lock method to obtain a row lock on a single reload (reloads the record with :lock => true). [Shugo Maeda]
     # Obtain an exclusive lock on person 1 so we can safely increment visits.
     Person.transaction do
       # select * from people where id=1 for update

activerecord/lib/active_record.rb

@@ -46,7 +46,8 @@ require 'active_record/timestamp'
 require 'active_record/acts/list'
 require 'active_record/acts/tree'
 require 'active_record/acts/nested_set'
-require 'active_record/locking'
+require 'active_record/locking/optimistic'
+require 'active_record/locking/pessimistic'
 require 'active_record/migration'
 require 'active_record/schema'
 require 'active_record/calculations'
@@ -55,6 +56,7 @@ require 'active_record/xml_serialization'
 ActiveRecord::Base.class_eval do
   include ActiveRecord::Validations
   include ActiveRecord::Locking::Optimistic
+  include ActiveRecord::Locking::Pessimistic
   include ActiveRecord::Callbacks
   include ActiveRecord::Observing
   include ActiveRecord::Timestamp

activerecord/lib/active_record/base.rb

@@ -1541,10 +1541,13 @@ module ActiveRecord #:nodoc:
       end
 
       # Reloads the attributes of this object from the database.
-      def reload
+      # The optional options argument is passed to find when reloading so you
+      # may do e.g. record.reload(:lock => true) to reload the same record with
+      # an exclusive row lock.
+      def reload(options = nil)
         clear_aggregation_cache
         clear_association_cache
-        @attributes.update(self.class.find(self.id).instance_variable_get('@attributes'))
+        @attributes.update(self.class.find(self.id, options).instance_variable_get('@attributes'))
         self
       end
 

activerecord/lib/active_record/locking/optimistic.rb

@@ -49,8 +49,8 @@ module ActiveRecord
         affected_rows = connection.update(<<-end_sql, "#{self.class.name} Update with optimistic locking")
           UPDATE #{self.class.table_name}
           SET #{quoted_comma_pair_list(connection, attributes_with_quotes(false))}
-          WHERE #{self.class.primary_key} = #{quote(id)} 
+          WHERE #{self.class.primary_key} = #{quote(id)}
-          AND #{lock_col} = #{quote(previous_value)}
+          AND #{self.class.quoted_locking_column} = #{quote(previous_value)}
         end_sql
 
         unless affected_rows == 1
@@ -74,6 +74,11 @@ module ActiveRecord
           reset_locking_column
         end
 
+        # Quote the column name used for optimistic locking.
+        def quoted_locking_column
+          connection.quote_column_name(locking_column)
+        end
+
         # Reset the column used for optimistic locking back to the lock_version default.
         def reset_locking_column
           set_locking_column DEFAULT_LOCKING_COLUMN

activerecord/lib/active_record/locking/pessimistic.rb

@@ -0,0 +1,77 @@
+# Copyright (c) 2006 Shugo Maeda <shugo@ruby-lang.org>
+#
+# 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.
+
+
+module ActiveRecord
+  module Locking
+    # Locking::Pessimistic provides support for row-level locking using
+    # SELECT ... FOR UPDATE and other lock types.
+    #
+    # Pass :lock => true to ActiveRecord::Base.find to obtain an exclusive
+    # lock on the selected rows:
+    #   # select * from accounts where id=1 for update
+    #   Account.find(1, :lock => true)
+    #
+    # Pass :lock => 'some locking clause' to give a database-specific locking clause
+    # of your own such as 'LOCK IN SHARE MODE' or 'FOR UPDATE NOWAIT'.
+    #
+    # Example:
+    #   Account.transaction do
+    #     # select * from accounts where name = 'shugo' limit 1 for update
+    #     shugo = Account.find(:first, :conditions => "name = 'shugo'", :lock => true)
+    #     yuko = Account.find(:first, :conditions => "name = 'yuko'", :lock => true)
+    #     shugo.balance -= 100
+    #     shugo.save!
+    #     yuko.balance += 100
+    #     yuko.save!
+    #   end
+    #
+    # You can also use ActiveRecord::Base#lock! method to lock one record by id.
+    # This may be better if you don't need to lock every row. Example:
+    #   Account.transaction do
+    #     # select * from accounts where ...
+    #     accounts = Account.find(:all, :conditions => ...)
+    #     account1 = accounts.detect { |account| ... }
+    #     account2 = accounts.detect { |account| ... }
+    #     # select * from accounts where id=? for update
+    #     account1.lock!
+    #     account2.lock!
+    #     account1.balance -= 100
+    #     account1.save!
+    #     account2.balance += 100
+    #     account2.save!
+    #   end
+    #
+    # Database-specific information on row locking:
+    #   MySQL: http://dev.mysql.com/doc/refman/5.1/en/innodb-locking-reads.html
+    #   PostgreSQL: http://www.postgresql.org/docs/8.1/interactive/sql-select.html#SQL-FOR-UPDATE-SHARE
+    module Pessimistic
+      # Obtain a row lock on this record. Reloads the record to obtain the requested
+      # lock. Pass an SQL locking clause to append the end of the SELECT statement
+      # or pass true for "FOR UPDATE" (the default, an exclusive row lock).  Returns
+      # the locked record.
+      def lock!(lock = true)
+        reload(:lock => lock) unless new_record?
+        self
+      end
+    end
+  end
+end

activerecord/test/locking_test.rb

@@ -82,6 +82,18 @@ class PessimisticLockingTest < Test::Unit::TestCase
     end
   end
 
+  # Locking a record reloads it.
+  def test_sane_lock_method
+    assert_nothing_raised do
+      Person.transaction do
+        person = Person.find 1
+        old, person.first_name = person.first_name, 'fooman'
+        person.lock!
+        assert_equal old, person.first_name
+      end
+    end
+  end
+
   if current_adapter?(:PostgreSQLAdapter)
     def test_no_locks_no_wait
       first, second = duel { Person.find 1 }