vendor/rails/activerecord/lib/active_record/locking/pessimistic.rb

   1 # Copyright (c) 2006 Shugo Maeda <shugo@ruby-lang.org>
   2 #
   3 # Permission is hereby granted, free of charge, to any person obtaining
   4 # a copy of this software and associated documentation files (the
   5 # "Software"), to deal in the Software without restriction, including
   6 # without limitation the rights to use, copy, modify, merge, publish,
   7 # distribute, sublicense, and/or sell copies of the Software, and to
   8 # permit persons to whom the Software is furnished to do so, subject
   9 # to the following conditions:
  10 #
  11 # The above copyright notice and this permission notice shall be
  12 # included in all copies or substantial portions of the Software.
  13 #
  14 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  15 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  18 # ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  19 # CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  20 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22
  23 module ActiveRecord
  24   module Locking
  25     # Locking::Pessimistic provides support for row-level locking using
  26     # SELECT ... FOR UPDATE and other lock types.
  27     #
  28     # Pass <tt>:lock => true</tt> to ActiveRecord::Base.find to obtain an exclusive
  29     # lock on the selected rows:
  30     #   # select * from accounts where id=1 for update
  31     #   Account.find(1, :lock => true)
  32     #
  33     # Pass <tt>:lock => 'some locking clause'</tt> to give a database-specific locking clause
  34     # of your own such as 'LOCK IN SHARE MODE' or 'FOR UPDATE NOWAIT'.
  35     #
  36     # Example:
  37     #   Account.transaction do
  38     #     # select * from accounts where name = 'shugo' limit 1 for update
  39     #     shugo = Account.find(:first, :conditions => "name = 'shugo'", :lock => true)
  40     #     yuko = Account.find(:first, :conditions => "name = 'yuko'", :lock => true)
  41     #     shugo.balance -= 100
  42     #     shugo.save!
  43     #     yuko.balance += 100
  44     #     yuko.save!
  45     #   end
  46     #
  47     # You can also use ActiveRecord::Base#lock! method to lock one record by id.
  48     # This may be better if you don't need to lock every row. Example:
  49     #   Account.transaction do
  50     #     # select * from accounts where ...
  51     #     accounts = Account.find(:all, :conditions => ...)
  52     #     account1 = accounts.detect { |account| ... }
  53     #     account2 = accounts.detect { |account| ... }
  54     #     # select * from accounts where id=? for update
  55     #     account1.lock!
  56     #     account2.lock!
  57     #     account1.balance -= 100
  58     #     account1.save!
  59     #     account2.balance += 100
  60     #     account2.save!
  61     #   end
  62     #
  63     # Database-specific information on row locking:
  64     #   MySQL: http://dev.mysql.com/doc/refman/5.1/en/innodb-locking-reads.html
  65     #   PostgreSQL: http://www.postgresql.org/docs/8.1/interactive/sql-select.html#SQL-FOR-UPDATE-SHARE
  66     module Pessimistic
  67       # Obtain a row lock on this record. Reloads the record to obtain the requested
  68       # lock. Pass an SQL locking clause to append the end of the SELECT statement
  69       # or pass true for "FOR UPDATE" (the default, an exclusive row lock).  Returns
  70       # the locked record.
  71       def lock!(lock = true)
  72         reload(:lock => lock) unless new_record?
  73         self
  74       end
  75     end
  76   end
  77 end