mongo-locking 0.0.1

data/LICENSE

@@ -0,0 +1 @@
+Still working this out.

data/README.txt

@@ -0,0 +1,42 @@
+##
+## 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
+#

data/Rakefile

@@ -0,0 +1,3 @@
+task :default do
+    puts "TBC"
+end

data/lib/mongo/locking.rb

@@ -0,0 +1,95 @@
+##
+## Mongo Locking Library
+##
+#
+# Despite the Locker being placed on the model classes, the dependency graph is
+# actually instance-based, thus the graph can only be resolved during runtime.
+#
+# Locking takes an instance to start with, optionally walks the graph through
+# parent "pointers" (procs whose arbitrary function produces the parent
+# lockable), then does the atomic incr/decr dance with the root lockable's key.
+#
+# TODO: More docs.  TBC.
+
+require 'mongo'
+require 'active_support/core_ext/module/delegation'
+
+module Mongo
+    module Locking
+        extend self
+
+        module Exceptions
+            class Error < RuntimeError;  end
+            class ArgumentError < Error; end # bad param
+            class InvalidConfig < Error; end # something bogus in config[]
+            class CircularLock  < Error; end # circular lock reference
+            class LockTimeout   < Error; end # lock failed, retries unsuccessful
+            class LockFailure   < Error; end # lock failed, something bad happened
+        end
+        include Exceptions
+
+        attr_accessor :logger, :collection
+        delegate      :debug, :info, :warn, :error, :fatal, :to => :logger, :allow_nil => true
+
+        def included(klass)
+            klass.send(:include, ModelMethods)
+        end
+
+        ##
+        ## Configuration
+        ##
+
+        def configure(opts = {})
+            opts.each { |k, v| send("#{k}=", v) }
+            return self
+        end
+
+        def collection=(new)
+            @collection = new
+            ensure_indices if @collection.kind_of? Mongo::Collection
+            return @collection
+        end
+
+        # Allow for a proc to be initially set as the collection, in case of
+        # delayed loading/configuration/whatever.  It'll only be materialized
+        # when first accessed, which is presumably either when ensure_indices is
+        # called imperatively, or more likely upon the first lock call.
+        def collection
+            if @collection.kind_of? Proc
+                @collection = @collection.call
+                ensure_indices if @collection.kind_of? Mongo::Collection
+            end
+            return @collection
+        end
+
+        ##
+        ## Document Indices
+        ##
+        #
+        # A Mongoid model would look like:
+        #   field :scope,     :type => String
+        #   field :key,       :type => String
+        #   field :refcount,  :type => Integer, :default => 0
+        #   field :expire_at, :type => DateTime
+        #   index [ [ :scope, Mongo::ASCENDING ], [ :key, Mongo::ASCENDING ] ], :unique => true
+        #   index :refcount
+        #   index :expire_at
+
+        LOCK_INDICES = {
+            [["scope", Mongo::ASCENDING], ["key", Mongo::ASCENDING]] => { :unique => true,  :background => true },
+            [["refcount", Mongo::ASCENDING]]                         => { :unique => false, :background => true },
+            [["expire_at", Mongo::ASCENDING]]                        => { :unique => false, :background => true },
+        }
+
+        def ensure_indices
+            LOCK_INDICES.each do |spec, opts|
+                @collection.ensure_index(spec, opts)
+            end
+        end
+
+    end # Locking
+end # Mongo
+
+require 'mongo/locking/locker'
+require 'mongo/locking/model_methods'
+

data/lib/mongo/locking/locker.rb

@@ -0,0 +1,274 @@
+# 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
+
+        class Locker
+            include Exceptions
+
+            attr_reader :config
+
+            DEFAULT_OPTIONS = {
+                :max_retries          => 5,
+                :first_retry_interval => 0.2.seconds,
+                :max_retry_interval   => 5.seconds,
+                :max_lifetime         => 10.minutes,
+            }
+
+            def initialize(opts = {})
+                @config       = DEFAULT_OPTIONS.merge(opts)
+                @refcount_key = "mongo_locking_refcounts_#{@config[:class_name]}"
+            end
+
+            def refcounts
+                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)
+                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
+
+                refcounts[key] += 1
+                if refcounts[key] > 1
+                    Locking.info "acquire: re-using lock for #{name}##{refcounts[key]}"
+                    return true
+                end
+
+                target   = { :scope => scope, :key => key }
+                interval = self.config[:first_retry_interval]
+                retries  = 0
+
+                Locking.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"
+                        raise LockFailure
+                    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"
+                        raise LockFailure
+                    end
+
+                rescue LockFailure => e
+                    retries += 1
+                    if retries >= self.config[:max_retries]
+                        refcounts[key] -= 1
+                        raise LockTimeout, "unable to acquire lock #{name}"
+                    end
+
+                    Locking.warn "acquire: #{name} refcount #{refcount}, retry #{retries} for lock"
+
+                    sleep(interval.to_f)
+                    interval = [self.config[:max_retry_interval].to_f, interval * 2].min
+                    retry
+
+                rescue => e
+                    refcounts[key] -= 1
+
+                    log_exception(e)
+                    raise LockFailure, "unable to acquire lock #{name}"
+                end
+
+                Locking.info "acquire: #{name} locked (#{refcount})"
+
+                return true
+            end
+
+            def release(scope, key)
+                name = scope + "/" + key
+
+                refcounts[key] -= 1
+                if refcounts[key] > 0
+                    Locking.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
+                    end
+
+                rescue => e
+                    log_exception(e)
+                    raise LockFailure, "unable to release lock #{name}"
+                end
+            end
+
+            def root_for(from)
+                lockable = from
+                visited  = Set.new([lockable.class])
+
+                while parent = lockable.class.locker.parent_for(lockable)
+                    lockable = parent
+
+                    if visited.include? lockable.class
+                        raise CircularLock, "already visited #{lockable.class} (#{visited.inspect})"
+                    end
+
+                    visited << lockable.class
+                end
+
+                raise InvalidConfig, "root #{lockable.inspect} is not lockable" unless lockable.class.locker.is_root?
+
+                return lockable
+            end
+
+            def key_for(lockable)
+                return case key = self.config[:key]
+                    when Proc   then key.call(self).to_s
+                    when Symbol then lockable.send(key).to_s
+                    else raise InvalidConfig, "unknown key type #{key.inspect}"
+                end
+            end
+
+            def scope_for(lockable)
+                return case scope = self.config[:scope]
+                    when Proc   then scope.call(lockable).to_s
+                    when Symbol then scope.to_s
+                    when String then scope
+                    else raise InvalidConfig, "unknown scope type #{scope.inspect}"
+                end
+            end
+
+            def parent_for(lockable)
+                return case parent = self.config[:parent]
+                   when Proc     then parent.call(self)
+                   when Symbol   then lockable.send(parent)
+                   when NilClass then nil
+                   else raise InvalidConfig, "unknown parent type #{parent.inspect}"
+                end
+            end
+
+            def is_root?
+                self.config[:parent].blank?
+            end
+
+            private
+
+            def log_exception(e)
+                Locking.error e.inspect + " " + e.backtrace[0..4].inspect
+            end
+
+            # Notes:
+            #
+            #   - search_hash contains mapping of search_key => search_value
+            #   - search_key is the key used to uniquely identify the document
+            #     to update
+            #   - search_key MUST be the sharding key if we do sharding
+            #     later. This ensures that "$atomic" still meaningful
+            #
+            # Mongo:
+            #
+            #   - $atomic actually means "write isolation". '$atomic'=>1 means
+            #     we are the only writer to this document.
+            #   - '$inc' means "atomic increment"
+            #   - set expire_at for future async/lazy lock reaping
+
+            def atomic_inc(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 => {
+                        '$inc' => update_hash.dup,
+                        '$set' => { 'expire_at' => self.config[:max_lifetime].from_now }
+                    },
+                })
+            end
+
+            def atomic_delete(search_hash)
+                return Locking.collection.find_and_modify({
+                    :query  => search_hash.merge({'$atomic' => 1}),
+                    :remove => true,
+                })
+            end
+
+        end # Locker
+    end # Locking
+end # Mongo

data/lib/mongo/locking/model_methods.rb

@@ -0,0 +1,101 @@
+require 'active_support/concern'
+require 'active_support/core_ext/array/extract_options'
+require 'mongo/locking'
+
+module Mongo
+    module Locking
+
+        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:
+                #
+                #   :key   => Symbol (sent to self), Proc (passed self) -> result.to_s
+                #   :scope => String, Symbol (default self.name)
+                #
+                #   :max_retries          => default 5
+                #   :first_retry_interval => default 0.2.seconds
+                #   :max_retry_interval   => default 5.seconds
+                #   :max_lifetime         => default 1.minute
+                #
+                def lockable!(opts = {})
+                    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
+                end
+
+                # Options:
+                #
+                #   :parent => instance of lockable parent
+                #
+                def locked_by!(*args, &parent)
+                    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})"
+
+                    self
+                end
+
+            end # ClassMethods
+
+            module InstanceMethods
+
+                # Main closure-based lock method.  opts remains present for
+                # future utility.
+                def lock(opts = {})
+                    raise ArgumentError, "#{self.class.name}#lock requires a block" unless block_given?
+
+                    lockable = self.class.locker.lock(self)
+
+                    return yield
+
+                rescue => e
+                    Locking.error "#{self.class.name}#lock failed"
+                    raise e
+
+                ensure
+                    # Only unlock if lockable 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
+                    # within the closure, too.
+                    #
+                    # 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
+                end
+
+            end # InstanceMethods
+
+        end # ModelMethods
+    end # Locking
+end # Mongo

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification 
+name: mongo-locking
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jordan Ritter
+- Brendan Baldwin
+- Yanzhu Du
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-13 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongo
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 1
+        - 3
+        - 1
+        version: 1.3.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: active_support
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 3
+        - 0
+        - 4
+        version: 3.0.4
+  type: :runtime
+  version_requirements: *id002
+description: A mixin DSL for implementing cross-process mutexes/locks using MongoDB
+email: jpr5@serv.io
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+- LICENSE
+files: 
+- LICENSE
+- README.txt
+- Rakefile
+- lib/mongo/locking/locker.rb
+- lib/mongo/locking/model_methods.rb
+- lib/mongo/locking.rb
+has_rdoc: true
+homepage: http://github.com/servio/mongo-locking
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A mixin DSL for implementing cross-process mutexes/locks using MongoDB
+test_files: []
+