mongo-locking 0.0.1 → 0.0.2

data/LICENSE

@@ -1 +1,20 @@
-Still working this out.
+Copyright (c) 2011 Servio, Inc.
+
+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 THE EVENT THIS SOFTWARE GETS
+YOU LAID OR MAKES YOU A MILLION DOLLARS, YOU AGREE HERETOFORE TO BUY JORDAN
+RITTER A MONSTER TRUCK.  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/README.md

@@ -0,0 +1,229 @@
+### Summary
+
+Mongo::Locking is a library that enables cross-process blocking mutexes, using
+simple but flexible primitives to express an arbitrary graph of lock
+dependencies between class instances.
+
+#### Background
+
+Consider the following common scenario:
+
+Given an object graph 1 Order -> N OrderItems -> 1 JobFlow -> N Jobs, a
+collection of disparate systems that operate on portions of the graph
+asynchronously.
+
+If you were using a Document-oriented (e.g. Mongo) data model, you might
+represent the object graph as a bunch of nested objects, rooted in an Order.  In
+an RDBMS, you usually have a collection of tables with foreign key relationships
+between them.
+
+In any case, you need to enforce some notion of data integrity as portions of
+the graph mutate.  How does one normally enforce integrity in concurrent access
+scenarios?
+
+#### RDBMS
+
+In the RDBMS world, you've got a couple options:
+
+1. `SELECT .. FOR UPDATE` or equivalent.
+
+    Depending on the underlying storage engine, this will write lock at minimum
+    the given row, and in most modern RDBMS', a cluster of rows around the row
+    you're trying to "protect".  This approach tends to require breaking out of
+    the ORM with custom SQL, and carries with it all sorts of
+    unintended/unexpected performance/synchronization/deadlock pitfalls.  It
+    really starts to break down when there is more than one object that needs to
+    be "locked", multiple loosely-related objects that need to be "locked", or
+    when crossing database boundaries.
+
+2. Rely on the ACID properties of SQL92 transactions to enforce data integrity.
+
+    (a) Given 2 or more competing, disparate processes running asynchronously,
+    accessing the same resources.  Both enter into transactions, possibly access
+    overlapping resources, one wins and the other (eventually) fails after
+    attempting to commit.
+
+    Practically, what does the erroring code do?  Does it retry?  Was it written
+    in a way that even makes a retry possible?  Is the context so consistently
+    atomic and stateless that it could blindly do so?  Does it just bail and
+    fail?  (Yes, most of the time.)  What if it was acting on an asynchronous
+    imperative across a message bus?  Shouldn't this condition be detected, and
+    the imperative replayed by some other code somewhere else?  Wouldn't that
+    vary depending upon the logical atomicity of the operation?  Etc etc.
+
+    (b) Given 2 competing processes, both enter into transactions, but the
+    relationship between resources is *not* fully expressed in terms of RDBMS
+    constraints.  This is another very common case, as most ORMs tend to provide
+    integrity (validation) functionality in the app layer, and only a subset
+    actually trickle down into material RDBMS constraints.  In this case, the
+    RDBMS has no idea that logical integrity has been violated, and general
+    misery will ensue.
+
+    Transactions are often mistakenly perceived as a panacea for these types of
+    of problems, and as a consequence usually compound the problems they are
+    being used to solve with additional complexity and cost.
+
+### NoSQL
+
+In the NoSQL world, you don't have as many options.  Many folks mistakenly
+believe that logically embedded objects are somehow protected by that nesting.
+(They aren't.)
+
+Some engines provide unique locking or pseudo-transactional primitive(s), but
+generally the same costs and pitfalls of transactions apply.  Especially so, in
+distributed, partitioned environments.
+
+### A Solution
+
+However, when certain requirements are satisfied, one mechanism can
+substantively bridge the gap: atomic increment/decrement.  Anything that
+implements it can be used to build a mutual-exclusion/locking system.  And
+that's what this library does.
+
+Qualities:
+
+- must be reasonably "fast" (hash-time lookup)
+- must be non-blocking ("retry-able")
+- must be recoverable (expiration of dead/stale locks)
+- must be able to be monitored / administered
+
+Behaviour:
+
+- blocks for a configurable duration when acquiring a lock across execution threads
+- *doesn't* block when (re-)acquiring a lock within the same thread of execution
+
+
+.... TBC ....
+
+
+
+### Usage
+
+Mongo::Locking makes no effort to help configure the MongoDB connection - that's
+what the Mongo Ruby Driver is for.  However, when the collection is specified as
+a proc, it will be lazily resolved during the first invocation of a lock.  This
+makes the concern of load/initialization order largely irrelevant.
+
+Configuring Mongo::Locking with the Mongo Ruby Driver would look like this:
+
+```ruby
+::Mongo::Locking.configure(:collection => proc {
+    ::Mongo::Connection.new("localhost").db("somedb").collection("locks")
+})
+```
+
+Or using Mongoid:
+
+```ruby
+::Mongo::Locking.configure({
+    :collection => proc { ::Mongoid.database.collection("locks") },
+    :logger     => Logger.new(STDOUT),
+})
+```
+
+While Mongo::Locking depends on Mongo, it can be applied to any arbitrary object
+model structure, including other ORMs.  All locks have a namespace (scope) and a
+key (some instance-related value), classes can depend on others for their locks,
+and the dependency graph is resolved at invocation-time.
+
+Consider this simplified example of using it with DataMapper:
+
+```ruby
+class Order
+    include ::DataMapper::Resource
+    include ::Mongo::Locking
+
+    has n, :order_items
+
+    lockable!
+end
+
+class OrderItem
+    include ::DataMapper::Resource
+    include ::Mongo::Locking
+
+    belongs_to :order
+    has 1, :job_flow
+
+    # invokes method to get "parent" lockable
+    locked_by! :order
+end
+
+class JobFlow
+    include ::DataMapper::Resource
+    include ::Mongo::Locking
+
+    belongs_to :order_item
+
+    # also takes a closure, yielding some abitrary "parent" lockable
+    locked_by! { |me| me.order_item }
+end
+```
+
+Other (simplified) graph configuration imperatives:
+
+```ruby
+Order.lockable! :key => :id
+Order.lockable! :scope => "OtherClass"
+Order.lockable! :key => proc { |me| SHA1.hexdigest(me.balls) }
+
+OrderItem.locked_by! { |me| me.order }
+OrderItem.locked_by! :parent => proc { |me| me.order }
+OrderItem.locked_by! :order
+OrderItem.locked_by! :parent => :order
+```
+
+And then, a contrived use case:
+
+```ruby
+order = Order.get(1)
+order.lock do
+    # ...
+
+    order.order_items.each do |item|
+        item.lock do
+
+            # this won't block even though the same lock is being acquired
+
+        end
+    end
+end
+```
+
+Not blocking on lock re-acquisition means save hooks on models can be as
+defensive as controller methods operating on them: both can lock, and it will
+Just Work.
+
+Pretty neat!
+
+
+### Testing
+
+Testing concurrency is "difficult", especially in Ruby.  So for now, here's some
+irb/console-level tests that you can use to test the library with:
+
+Given:
+
+    Pn == process N
+    Order.id == 1
+    OrderItem.id == 1, OrderItem.order_id = 1
+
+1. General race, same object
+
+        P1: Order.first.lock { debugger }  # gets and holds lock
+        P2: Order.first.lock { puts "hi" } # retries acquire, fails
+
+2. General race, locked root, attempt to lock from child
+
+        P1: Order.first.lock { debugger }      # gets and holds lock
+        P2: OrderItem.first.lock { puts "hi" } # retries acquire, fails
+
+3. General race, locked root from child, attempt to lock from child
+
+        P1: OrderItem.first.lock { debugger }  # gets and holds lock
+        P2: OrderItem.first.lock { puts "hi" } # retries acquire, fails
+
+4. Nested lock acquisition
+
+        P1: Order.first.lock { puts "1"; Order.first.lock { puts "2" } }
+        # should see 1 and 2

data/Rakefile

@@ -1,3 +1,7 @@
 task :default do
-    puts "TBC"
+    Kernel.exec("#{$0}", '-T')
+end
+
+task :gem do
+    `gem build mongo-locking.gemspec`
 end

data/lib/mongo/locking/locker.rb

@@ -1,27 +1,28 @@
-# Locker is a container for locking related commands, so we minimally impact the
-# model's namespace.
-#
-# In addition to the Mongo-based, per-process, blocking lock mechanism itself,
-# we also employ a thread-local lock refcount to achieve non-blocking behaviour
-# when nesting lock closures.  This is useful for when multiple, isolated code
-# paths are all defensive with locks, but are arbitrarily called within the same
-# thread of execution.
-#
-# We try to limit the number of these objects, so as to minimze extra cost
-# attached to model instance hydration.  Thus the Locker is attached to the
-# model class, and maintains refcounts based on the key it's configured with.
-
 require 'mongo/locking'
 require 'active_support/core_ext/numeric/time'
-require 'active_support/core_ext/object/blank'
 
 module Mongo
     module Locking
 
+        # Locker is a container for isolating all the locking-related methods,
+        # so we minimally impact the namespace of wherever we're mixed into.
+        #
+        # In addition to the Mongo-based, per-process, blocking lock mechanism
+        # itself, we also employ a thread-local lock refcount to achieve
+        # non-blocking behaviour when nesting lock closures.  This is useful for
+        # when multiple, isolated code paths are all defensive with locks, but
+        # are arbitrarily called within the same thread of execution.
+        #
+        # We try to limit the number of these objects, so as to minimize extra
+        # cost attached to model instance hydration.  Thus the Locker is
+        # attached to the model class, and maintains refcounts based on the key
+        # it's configured with.
+
         class Locker
             include Exceptions
 
             attr_reader :config
+            delegate    :debug, :info, :warn, :error, :fatal, :to => Locking
 
             DEFAULT_OPTIONS = {
                 :max_retries          => 5,
@@ -39,82 +40,92 @@ module Mongo
                 Thread.current[@refcount_key] ||= Hash.new(0)
             end
 
-            def lock(from)
-                lockable = root_for(from)
-                locker   = lockable.class.locker
-
-                key   = locker.key_for(lockable)
-                scope = locker.scope_for(lockable)
-
-                locker.acquire(scope, key)
-
-                return lockable
-            end
-
-            def unlock(from)
+            # We increment refcounts ASARP so that any further (nested) calls
+            # won't block.  But that means we have to make sure to decrement it
+            # on any failure case.
+            def acquire(from)
                 lockable = root_for(from)
                 locker   = lockable.class.locker
-
-                key   = locker.key_for(lockable)
-                scope = locker.scope_for(lockable)
-
-                locker.release(scope, key)
-
-                return lockable
-            end
-
-            # refcounts[] is about enabling non-blocking behaviour when the
-            # process has already acquired the lock (e.g. controller locks
-            # Order, calls model save method that also locks Order).  In a way,
-            # it's like an IdentityMap, mapping instance keys to reference
-            # counts (another reason it lives on the class and not the
-            # instance).
-            #
-            # We increment it immediately so that any further (nested) calls
-            # won't block, but that means we have to make sure to decrement it
-            # on every failure case.
-            def acquire(scope, key)
-                name = scope + "/" + key
+                scope    = locker.scope_for(lockable)
+                key      = locker.key_for(lockable)
+                name     = scope + "/" + key
 
                 refcounts[key] += 1
                 if refcounts[key] > 1
-                    Locking.info "acquire: re-using lock for #{name}##{refcounts[key]}"
-                    return true
+                    info "acquire: re-using lock for #{name}##{refcounts[key]}"
+                    return lockable
                 end
 
                 target   = { :scope => scope, :key => key }
                 interval = self.config[:first_retry_interval]
                 retries  = 0
 
-                Locking.debug "acquire: attempting lock of #{name}"
+                debug "acquire: attempting lock of #{name}"
 
                 begin
                     a_lock   = atomic_inc(target, { :refcount => 1 })
                     refcount = a_lock['refcount']
 
-                    # FIXME: If the lock is "expired" then we just inherit the
-                    # lock and assume the user of the lock is "gone", right?  Do
-                    # we need to do some decr/incr?  Is this correct?
-                    if a_lock['expire_at'] < Time.now
-                        refcount = 1
-                    end
-
                     # If the refcount is 0 or somehow less than 0, after we just
                     # incremented, then retry without counting against the max.
                     if refcount < 1
                         retries -= 1
-                        Locking.debug "acquire: refcount #{refcount}, unexpected state"
+                        debug "acquire: refcount #{refcount}, unexpected state"
                         raise LockFailure
                     end
 
+                    # Check lock expiration.
+                    if a_lock.has_key?('expire_at') and a_lock['expire_at'] < Time.now
+
+                        # If the lock is "expired". We assume the owner of the
+                        # lock is "gone" without decrementing the refcount.
+                        warn "acquire: #{name} lock expired"
+
+                        # Attempt to decrement the refcount to "reverse" the
+                        # damage caused by the "gone" process.  There might be
+                        # more than one process trying to do this at the same
+                        # time.  Therefore, we need the refcount > 1 guard.  If
+                        # the lock's refcount is no longer > 1 by the time this
+                        # process try to decrement, Mongo will raise a
+                        # Mongo::OperationFailure.  Regardless of reason, if it
+                        # fails, we fail.
+                        a_lock = atomic_inc(target.merge({:refcount => {'$gt' => 1} }), { :refcount => -1 }) rescue nil
+
+                        unless a_lock
+                            # We lost the race to "reverse" the damage.  Someone
+                            # else has the lock now.  We will retry.
+                            raise LockFailure
+                        end
+
+                        # We have won the race to "reverse" the damage but we
+                        # may have not "reversed" enough of the damage.
+                        # Consider the case that the expired lock has a large
+                        # refcount - we still need to check refcount to make
+                        # sure that we are have acquired the lock.
+                        refcount = a_lock['refcount']
+
+                        # The rest of the expired_lock handling logic coincides
+                        # with normal lock logic.
+                    end
+
                     # If recount is greater than 1, we lost the race.  Decrement
                     # and try again.
                     if refcount > 1
                         atomic_inc(target, { :refcount => -1 })
-                        Locking.debug "acquire: refcount #{refcount}, race lost"
+                        debug "acquire: refcount #{refcount}, race lost"
                         raise LockFailure
                     end
 
+                    # If refcount == 1, we have the lock and thus renew
+                    # its expire_at.
+                    #
+                    # NOTE: This expire_at renewal only happens when a process
+                    # acquires the lock for the first time.  Subsequent lock
+                    # reuse will NOT renew expire_at.  This assumes that all
+                    # legitimate operations should complete within
+                    # config[:max_lifetime] time limit.
+                    atomic_update(target, {'expire_at' => self.config[:max_lifetime].from_now})
+
                 rescue LockFailure => e
                     retries += 1
                     if retries >= self.config[:max_retries]
@@ -122,7 +133,7 @@ module Mongo
                         raise LockTimeout, "unable to acquire lock #{name}"
                     end
 
-                    Locking.warn "acquire: #{name} refcount #{refcount}, retry #{retries} for lock"
+                    warn "acquire: #{name} refcount #{refcount}, retry #{retries} for lock"
 
                     sleep(interval.to_f)
                     interval = [self.config[:max_retry_interval].to_f, interval * 2].min
@@ -135,49 +146,57 @@ module Mongo
                     raise LockFailure, "unable to acquire lock #{name}"
                 end
 
-                Locking.info "acquire: #{name} locked (#{refcount})"
+                info "acquire: #{name} locked (#{refcount})"
 
-                return true
+                return lockable
             end
 
-            def release(scope, key)
-                name = scope + "/" + key
+            def release(from)
+                lockable = root_for(from)
+                locker   = lockable.class.locker
+                key      = locker.key_for(lockable)
+                scope    = locker.scope_for(lockable)
+                name     = scope + "/" + key
 
                 refcounts[key] -= 1
                 if refcounts[key] > 0
-                    Locking.info "release: re-using lock for #{name}##{refcounts[key]}"
+                    info "release: re-using lock for #{name}##{refcounts[key]}"
                     return true
                 end
 
                 target = { :scope => scope, :key => key }
 
-                begin
-                    refcount = atomic_inc(target, { :refcount => -1 })['refcount']
-
-                    Locking.info "release: #{name} unlocked (#{refcount})"
-
-                    # If the refcount is at zero, nuke it out of the table.
-                    #
-                    # FIXME: If the following delete fails (e.g. something else
-                    # incremented it before we tried to delete it), it will
-                    # raise:
-                    #
-                    #    <Mongo::OperationFailure: Database command 'findandmodify'
-                    #       failed: {"errmsg"=>"No matching object found", "ok"=>0.0}>
-                    #
-                    # Need to see if there's a way to report the error
-                    # informationally instead of exceptionally.  'rescue nil'
-                    # hack in place until something more correct is put in.
-                    if refcount == 0
-                        unless hash = atomic_delete(target.merge({ :refcount => 0 })) rescue nil
-                            Locking.debug "release: lock #{name} no longer needed, deleted"
-                        end
+                refcount = atomic_inc(target, { :refcount => -1 })['refcount']
+
+                info "release: #{name} unlocked (#{refcount})"
+
+                # If the refcount is at zero, nuke it out of the table.
+                #
+                # NOTE: If the following delete fails (e.g. something else
+                # incremented it before we tried to delete it), it will raise:
+                #
+                #    <Mongo::OperationFailure: Database command 'findandmodify'
+                #       failed: {"errmsg"=>"No matching object found", "ok"=>0.0}>
+                #
+                # This is normal for a concurrent system.
+                #
+                # Since a lock with refcount 0 does not impact lock functionality,
+                # we can also ignore any other exceptions during lock deletion.
+                #
+                # We use 'rescue nil' to ignore all exceptions.
+                if refcount == 0
+                    if hash = atomic_delete(target.merge({ :refcount => 0 })) rescue nil
+                        debug "release: lock #{name} no longer needed, deleted"
                     end
 
-                rescue => e
-                    log_exception(e)
-                    raise LockFailure, "unable to release lock #{name}"
+                    # Nuke the key from our instance refcounts so we don't
+                    # balloon during long-lived processes.
+                    refcounts.delete(key)
                 end
+
+            rescue => e
+                log_exception(e)
+                raise LockFailure, "unable to release lock #{name}"
             end
 
             def root_for(from)
@@ -218,7 +237,7 @@ module Mongo
 
             def parent_for(lockable)
                 return case parent = self.config[:parent]
-                   when Proc     then parent.call(self)
+                   when Proc     then parent.call(lockable)
                    when Symbol   then lockable.send(parent)
                    when NilClass then nil
                    else raise InvalidConfig, "unknown parent type #{parent.inspect}"
@@ -226,13 +245,14 @@ module Mongo
             end
 
             def is_root?
-                self.config[:parent].blank?
+                self.config[:parent].nil?
             end
 
             private
 
+            # Separated out in case you want to monkeypatch it into oblivion.
             def log_exception(e)
-                Locking.error e.inspect + " " + e.backtrace[0..4].inspect
+                error e.inspect + " " + e.backtrace[0..4].inspect
             end
 
             # Notes:
@@ -255,10 +275,16 @@ module Mongo
                     :new    => true,    # Return the updated document
                     :upsert => true,    # Update if document exists, insert if not
                     :query  => search_hash.merge({'$atomic' => 1}),
-                    :update => {
-                        '$inc' => update_hash.dup,
-                        '$set' => { 'expire_at' => self.config[:max_lifetime].from_now }
-                    },
+                    :update => {'$inc' => update_hash.dup},
+                })
+            end
+
+            def atomic_update(search_hash, update_hash)
+                return Locking.collection.find_and_modify({
+                    :new    => true,    # Return the updated document
+                    :upsert => true,    # Update if document exists, insert if not
+                    :query  => search_hash.merge({'$atomic' => 1}),
+                    :update => {'$set' => update_hash.dup},
                 })
             end
 
@@ -272,3 +298,4 @@ module Mongo
         end # Locker
     end # Locking
 end # Mongo
+

data/lib/mongo/locking/model_methods.rb

@@ -8,14 +8,6 @@ module Mongo
         module ModelMethods
             extend ::ActiveSupport::Concern
 
-            included do
-                # We don't want people modifying this attribute, but it needs to
-                # be accessible from the outside.
-                class << self
-                    attr_reader :locker
-                end
-            end
-
             module ClassMethods
 
                 # Options:
@@ -32,16 +24,13 @@ module Mongo
                     key   = opts[:key]   ||= :id
                     scope = opts[:scope] ||= self.name
 
-                    raise ArgumentError, "locker already defined" if self.locker
                     raise ArgumentError, "locker key must be a Proc or Symbol" unless [Proc, Symbol].include?(key.class)
                     raise ArgumentError, "locker scope must be a Proc, Symbol or String" unless [Proc, Symbol, String].include?(scope.class)
 
                     opts[:class_name] = self.name
                     @locker = Locker.new(opts)
 
-                    Locking.debug "#{self.name} is lockable (#{opts.inspect})"
-
-                    self
+                    return self
                 end
 
                 # Options:
@@ -52,16 +41,18 @@ module Mongo
                     opts   = args.extract_options!
                     parent = opts[:parent] ||= parent || args.first
 
-                    raise ArgumentError, "locker already defined" if self.locker
                     raise ArgumentError, "parent reference must be a Proc or Symbol" unless [Proc, Symbol].include?(parent.class)
 
                     opts[:class_name] = self.name
 
                     @locker = Locker.new(opts)
 
-                    Locking.debug "#{self.name} is locked_by (#{opts.inspect})"
+                    return self
+                end
 
-                    self
+                # No-frills class-inheritable locker reference
+                def locker
+                    @locker ||= (superclass.locker if superclass.respond_to?(:locker))
                 end
 
             end # ClassMethods
@@ -73,7 +64,11 @@ module Mongo
                 def lock(opts = {})
                     raise ArgumentError, "#{self.class.name}#lock requires a block" unless block_given?
 
-                    lockable = self.class.locker.lock(self)
+                    # Look for the top level lockable
+                    lockable = self.class.locker.root_for(self)
+
+                    # Try to acquire the lock. If succeeds, "locked" will be set
+                    locked = lockable.class.locker.acquire(lockable)
 
                     return yield
 
@@ -82,7 +77,7 @@ module Mongo
                     raise e
 
                 ensure
-                    # Only unlock if lockable was set.  We're using this to
+                    # Only unlock if "locked" was set.  We're using this to
                     # distinguish between an exception from the yield vs. an
                     # exception from our own locking code.  Doing it in an
                     # ensure block makes us defensible against a return from
@@ -91,7 +86,7 @@ module Mongo
                     # Calling lockable's locker instead of self potentially
                     # saves us the cost of "find root lockable" that locker
                     # would perform.
-                    lockable.class.locker.unlock(lockable) if lockable
+                    lockable.class.locker.release(lockable) if locked
                 end
 
             end # InstanceMethods
@@ -99,3 +94,4 @@ module Mongo
         end # ModelMethods
     end # Locking
 end # Mongo
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mongo-locking
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jordan Ritter
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-13 00:00:00 -07:00
+date: 2011-07-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,18 +52,18 @@ dependencies:
         version: 3.0.4
   type: :runtime
   version_requirements: *id002
-description: A mixin DSL for implementing cross-process mutexes/locks using MongoDB
+description: A mixin DSL for implementing cross-process mutexes/locks using MongoDB.
 email: jpr5@serv.io
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- README.txt
+- README.md
 - LICENSE
 files: 
 - LICENSE
-- README.txt
+- README.md
 - Rakefile
 - lib/mongo/locking/locker.rb
 - lib/mongo/locking/model_methods.rb
@@ -101,6 +101,6 @@ rubyforge_project:
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: A mixin DSL for implementing cross-process mutexes/locks using MongoDB
+summary: A mixin DSL for implementing cross-process mutexes/locks using MongoDB.
 test_files: []
 

data/README.txt

@@ -1,42 +0,0 @@
-##
-## Usages
-##
-#
-#   Order.lockable!
-#   Order.lockable! :key => :id
-#   Order.lockable! :key => proc { |me| SHA1.hexdigest(me.balls) }
-#   Order.lockable! :scope => "OtherClass"
-#
-#   OrderItem.locked_by! { |me| me.order }
-#   OrderItem.locked_by! :parent => proc { |me| me.order }
-#   OrderItem.locked_by! :order
-#   OrderItem.locked_by! :parent => :order
-#
-##
-## Useful tests
-##
-#
-#   Pn == process N
-#   Order.id == 1
-#   OrderItem.id == 1, OrderItem.order_id = 1
-#
-# - General race, same object
-#
-#   P1: Order.first.lock { debugger }  # gets and holds lock
-#   P2: Order.first.lock { puts "hi" } # retries acquire, fails
-#
-# - General race, locked root, attempt to lock from child
-#
-#   P1: Order.first.lock { debugger }  # gets and holds lock
-#   P2: OrderItem.first.lock { puts "hi" } # retries acquire, fails
-#
-# - General race, locked root from child, attempt to lock from child
-#
-#   P1: OrderItem.first.lock { debugger }  # gets and holds lock
-#   P2: OrderItem.first.lock { puts "hi" } # retries acquire, fails
-#
-# - Nested lock acquisition
-#
-#   P1: Order.first.lock { puts "1"; Order.first.lock { puts "2" } }
-#   # should see 1 and 2
-#