redis-em-mutex 0.1.2 → 0.2.0

data/lib/redis/em-mutex.rb

@@ -22,6 +22,7 @@ class Redis
     #
     class Mutex
 
+      autoload :NS, 'redis/em-mutex/ns'
       autoload :Macro, 'redis/em-mutex/macro'
 
       module Errors
@@ -46,62 +47,34 @@ class Redis
       @@ns = nil
       @@uuid = nil
 
-      attr_accessor :expire_timeout, :block_timeout
-      attr_reader :names, :ns
+      attr_reader :names, :ns, :block_timeout
       alias_method :namespace, :ns
 
-      class NS
-        attr_reader :ns
-        alias_method :namespace, :ns
-        # Creates a new namespace (Mutex factory).
-        #
-        # - ns = namespace
-        # - opts = options hash:
-        # - :block - default block timeout
-        # - :expire - default expire timeout
-        def initialize(ns, opts = {})
-          @ns = ns
-          @opts = (opts || {}).merge(:ns => ns)
-        end
-
-        # Creates a namespaced cross machine/process/fiber semaphore.
-        #
-        # for arguments see: Redis::EM::Mutex.new
-        def new(*args)
-          if args.last.kind_of?(Hash)
-            args[-1] = @opts.merge(args.last)
-          else
-            args.push @opts
-          end
-          Redis::EM::Mutex.new(*args)
-        end
+      def expire_timeout; @expire_timeout || @@default_expire; end
 
-        # Attempts to grab the lock and waits if it isn’t available.
-        # 
-        # See: Redis::EM::Mutex.lock
-        def lock(*args)
-          mutex = new(*args)
-          mutex if mutex.lock
-        end
+      def expire_timeout=(value)
+        raise ArgumentError, "#{self.class.name}\#expire_timeout value must be greater than 0" unless (value = value.to_f) > 0
+        @expire_timeout = value
+      end
 
-        # Executes block of code protected with namespaced semaphore.
-        #
-        # See: Redis::EM::Mutex.synchronize
-        def synchronize(*args, &block)
-          new(*args).synchronize(&block)
-        end
+      def block_timeout=(value)
+        @block_timeout = value.nil? ? nil : value.to_f
       end
 
       # Creates a new cross machine/process/fiber semaphore
       #
-      #   Redis::EM::Mutex.new(*names, opts = {})
+      #   Redis::EM::Mutex.new(*names, options = {})
       #
       # - *names = lock identifiers - if none they are auto generated
-      # - opts = options hash:
+      # - options = hash:
       # - :name - same as *names (in case *names arguments were omitted)
       # - :block - default block timeout
       # - :expire - default expire timeout (see: Mutex#lock and Mutex#try_lock)
       # - :ns - local namespace (otherwise global namespace is used)
+      # - :owner - owner definition instead of Fiber#__id__
+      #
+      # Raises MutexError if used before Mutex.setup.
+      # Raises ArgumentError on invalid options.
       def initialize(*args)
         raise MutexError, "call #{self.class}::setup first" unless @@redis_pool
 
@@ -109,13 +82,23 @@ class Redis
 
         @names = args
         @names = Array(opts[:name] || "#{@@name_index.succ!}.lock") if @names.empty?
-        raise MutexError, "semaphore names must not be empty" if @names.empty?
+        @slept = {}
+        raise ArgumentError, "semaphore names must not be empty" if @names.empty?
         @multi = !@names.one?
         @ns = opts[:ns] || @@ns
         @ns_names = @ns ? @names.map {|n| "#@ns:#{n}".freeze }.freeze : @names.map {|n| n.to_s.dup.freeze }.freeze
-        @expire_timeout = opts[:expire]
-        @block_timeout = opts[:block]
-        @locked_id = nil
+        self.expire_timeout = opts[:expire] if opts.key?(:expire)
+        self.block_timeout = opts[:block] if opts.key?(:block)
+        @locked_owner_id = @locked_id = nil
+        if (owner = opts[:owner])
+          self.define_singleton_method(:owner_ident) do |lock_id = nil|
+            if lock_id
+              "#@@uuid$#$$@#{owner} #{lock_id}"
+            else
+              "#@@uuid$#$$@#{owner}"
+            end
+          end
+        end
       end
 
       # Returns `true` if this semaphore (at least one of locked `names`) is currently being held by some owner.
@@ -129,49 +112,92 @@ class Redis
         end
       end
 
-      # Returns `true` if this semaphore (all the locked `names`) is currently being held by calling fiber
-      # (if executing fiber is the owner).
+      # Returns `true` if this semaphore (all the locked `names`) is currently being held by calling owner.
+      # This is the method you should use to check if lock is still held and valid.
       def owned?
-        !!if @locked_id
-          lock_full_ident = owner_ident(@locked_id)
+        !!if @locked_id && owner_ident(@locked_id) == (lock_full_ident = @locked_owner_id)
           @@redis_pool.mget(*@ns_names).all? {|v| v == lock_full_ident}
         end
       end
 
+      # Returns `true` when the semaphore is being held and have already expired.
+      # Returns `false` when the semaphore is still locked and valid
+      # or `nil` if the semaphore wasn't locked by current owner.
+      #
+      # The check is performed only on the Mutex object instance and should only be used as a hint.
+      # For reliable lock status information use #refresh or #owned? instead.
+      def expired?
+        Time.now.to_f > @locked_id.to_f if @locked_id && owner_ident(@locked_id) == @locked_owner_id
+      end
+
+      # Returns the number of seconds left until the semaphore expires.
+      # The number of seconds less than 0 means that the semaphore expired and could be grabbed
+      # by some other owner.
+      # Returns `nil` if the semaphore wasn't locked by current owner.
+      #
+      # The check is performed only on the Mutex object instance and should only be used as a hint.
+      # For reliable lock status information use #refresh or #owned? instead.
+      def expires_in
+        @locked_id.to_f - Time.now.to_f if @locked_id && owner_ident(@locked_id) == @locked_owner_id
+      end
+
+      # Returns local time at which the semaphore will expire or have expired.
+      # Returns `nil` if the semaphore wasn't locked by current owner.
+      #
+      # The check is performed only on the Mutex object instance and should only be used as a hint.
+      # For reliable lock status information use #refresh or #owned? instead.
+      def expires_at
+        Time.at(@locked_id.to_f) if @locked_id && owner_ident(@locked_id) == @locked_owner_id
+      end
+
+      # Returns timestamp at which the semaphore will expire or have expired.
+      # Returns `nil` if the semaphore wasn't locked by current owner.
+      #
+      # The check is performed only on the Mutex object instance and should only be used as a hint.
+      # For reliable lock status information use #refresh or #owned? instead.
+      def expiration_timestamp
+        @locked_id.to_f if @locked_id && owner_ident(@locked_id) == @locked_owner_id
+      end
+
       # Attempts to obtain the lock and returns immediately.
       # Returns `true` if the lock was granted.
-      # Use Mutex#expire_timeout= to set custom lock expiration time in secods.
+      # Use Mutex#expire_timeout= to set lock expiration time in secods.
       # Otherwise global Mutex.default_expire is used.
       #
-      # This method does not lock expired semaphores.
+      # This method doesn't capture expired semaphores
+      # and therefore it should not be used under normal circumstances.
       # Use Mutex#lock with block_timeout = 0 to obtain expired lock without blocking.
       def try_lock
-        lock_id = (Time.now + (@expire_timeout.to_f.nonzero? || @@default_expire)).to_f.to_s
+        lock_id = (Time.now + expire_timeout).to_f.to_s
+        lock_full_ident = owner_ident(lock_id)
         !!if @multi
-          lock_full_ident = owner_ident(lock_id)
           if @@redis_pool.msetnx(*@ns_names.map {|k| [k, lock_full_ident]}.flatten)
             @locked_id = lock_id
+            @locked_owner_id = lock_full_ident
           end
-        elsif @@redis_pool.setnx(@ns_names.first, owner_ident(lock_id))
+        elsif @@redis_pool.setnx(@ns_names.first, lock_full_ident)
           @locked_id = lock_id
+          @locked_owner_id = lock_full_ident
         end
       end
 
       # Refreshes lock expiration timeout.
-      # Returns true if refresh was successfull or false if mutex was not locked or has already expired.
+      # Returns `true` if refresh was successfull.
+      # Returns `false` if the semaphore wasn't locked or when it was locked but it has expired
+      # and now it's got a new owner.
       def refresh(expire_timeout=nil)
         ret = false
-        if @locked_id
-          new_lock_id = (Time.now + (expire_timeout.to_f.nonzero? || @expire_timeout.to_f.nonzero? || @@default_expire)).to_f.to_s
+        if @locked_id && owner_ident(@locked_id) == (lock_full_ident = @locked_owner_id)
+          new_lock_id = (Time.now + (expire_timeout.to_f.nonzero? || self.expire_timeout)).to_f.to_s
           new_lock_full_ident = owner_ident(new_lock_id)
-          lock_full_ident = owner_ident(@locked_id)
           @@redis_pool.execute(false) do |r|
             r.watch(*@ns_names) do
               if r.mget(*@ns_names).all? {|v| v == lock_full_ident}
-                ret = !!r.multi do |multi|
-                  multi.mset(*@ns_names.map {|k| [k, new_lock_full_ident]}.flatten)
+                if r.multi {|m| m.mset(*@ns_names.map {|k| [k, new_lock_full_ident]}.flatten)}
+                  @locked_id = new_lock_id
+                  @locked_owner_id = new_lock_full_ident
+                  ret = true
                 end
-                @locked_id = new_lock_id if ret
               else
                 r.unwatch
               end
@@ -181,16 +207,16 @@ class Redis
         ret
       end
 
-      # Releases the lock unconditionally.
-      # If semaphore wasn’t locked by the current owner it is silently ignored.
-      # Returns self.
-      def unlock
-        if @locked_id
-          lock_full_ident = owner_ident(@locked_id)
+      # Releases the lock. Returns self on success.
+      # Returns `false` if the semaphore wasn't locked or when it was locked but it has expired
+      # and now it's got a new owner.
+      def unlock!
+        ret = false
+        if @locked_id && owner_ident(@locked_id) == (lock_full_ident = @locked_owner_id)
           @@redis_pool.execute(false) do |r|
             r.watch(*@ns_names) do
               if r.mget(*@ns_names).all? {|v| v == lock_full_ident}
-                r.multi do |multi|
+                ret = !!r.multi do |multi|
                   multi.del(*@ns_names)
                   multi.publish SIGNAL_QUEUE_CHANNEL, Marshal.dump(@ns_names)
                 end
@@ -199,7 +225,16 @@ class Redis
               end
             end
           end
+          @locked_owner_id = @locked_id = nil
         end
+        ret && self
+      end
+
+      # Releases the lock unconditionally.
+      # If the semaphore wasn’t locked by the current owner it is silently ignored.
+      # Returns self.
+      def unlock
+        unlock!
         self
       end
 
@@ -215,7 +250,7 @@ class Redis
       # Use Mutex#expire_timeout= to set lock expiration timeout.
       # Otherwise global Mutex.default_expire is used.
       def lock(block_timeout = nil)
-        block_timeout||= @block_timeout
+        block_timeout||= self.block_timeout
         names = @ns_names
         timer = fiber = nil
         try_again = false
@@ -223,62 +258,97 @@ class Redis
           try_again = true
           ::EM.next_tick { fiber.resume if fiber } if fiber
         end
-        queues = names.map {|n| @@signal_queue[n] << handler }
-        ident_match = owner_ident
-        until try_lock
-          Mutex.start_watcher unless @@watching == $$
-          start_time = Time.now.to_f
-          expire_time = nil
-          @@redis_pool.execute(false) do |r|
-            r.watch(*names) do
-              expired_names = names.zip(r.mget(*names)).map do |name, lock_value|
-                if lock_value
-                  owner, exp_id = lock_value.split ' '
-                  exp_time = exp_id.to_f
-                  expire_time = exp_time if expire_time.nil? || exp_time < expire_time
-                  raise MutexError, "deadlock; recursive locking #{owner}" if owner == ident_match
-                  if exp_time < start_time
-                    name
+        begin
+          queues = names.map {|n| @@signal_queue[n] << handler }
+          ident_match = owner_ident
+          until try_lock
+            Mutex.start_watcher unless watching?
+            start_time = Time.now.to_f
+            expire_time = nil
+            @@redis_pool.execute(false) do |r|
+              r.watch(*names) do
+                expired_names = names.zip(r.mget(*names)).map do |name, lock_value|
+                  if lock_value
+                    owner, exp_id = lock_value.split ' '
+                    exp_time = exp_id.to_f
+                    expire_time = exp_time if expire_time.nil? || exp_time < expire_time
+                    raise MutexError, "deadlock; recursive locking #{owner}" if owner == ident_match
+                    if exp_time < start_time
+                      name
+                    end
                   end
                 end
-              end
-              if expire_time && expire_time < start_time
-                r.multi do |multi|
-                  expired_names = expired_names.compact
-                  multi.del(*expired_names)
-                  multi.publish SIGNAL_QUEUE_CHANNEL, Marshal.dump(expired_names)
+                if expire_time && expire_time < start_time
+                  r.multi do |multi|
+                    expired_names = expired_names.compact
+                    multi.del(*expired_names)
+                    multi.publish SIGNAL_QUEUE_CHANNEL, Marshal.dump(expired_names)
+                  end
+                else
+                  r.unwatch
                 end
-              else
-                r.unwatch
               end
             end
-          end
-          timeout = (expire_time = expire_time.to_f) - start_time
-          timeout = block_timeout if block_timeout && block_timeout < timeout
+            timeout = (expire_time = expire_time.to_f) - start_time
+            timeout = block_timeout if block_timeout && block_timeout < timeout
 
-          if !try_again && timeout > 0
-            timer = ::EM::Timer.new(timeout) do
-              timer = nil
-              ::EM.next_tick { fiber.resume if fiber } if fiber
+            if !try_again && timeout > 0
+              timer = ::EM::Timer.new(timeout) do
+                timer = nil
+                ::EM.next_tick { fiber.resume if fiber } if fiber
+              end
+              fiber = Fiber.current
+              Fiber.yield
+              fiber = nil
+            end
+            finish_time = Time.now.to_f
+            if try_again || finish_time > expire_time
+              block_timeout-= finish_time - start_time if block_timeout
+              try_again = false
+            else
+              return false
             end
-            fiber = Fiber.current
-            Fiber.yield 
-            fiber = nil
           end
-          finish_time = Time.now.to_f
-          if try_again || finish_time > expire_time
-            block_timeout-= finish_time - start_time if block_timeout
-            try_again = false
-          else
-            return false
+          true
+        ensure
+          timer.cancel if timer
+          timer = nil
+          queues.each {|q| q.delete handler }
+          names.each {|n| @@signal_queue.delete(n) if @@signal_queue[n].empty? }
+        end
+      end
+
+      # Wakes up currently sleeping fiber on a mutex.
+      def wakeup(fiber)
+        fiber.resume if @slept.delete(fiber)
+      end
+
+      # for compatibility with EventMachine::Synchrony::Thread::ConditionVariable
+      alias_method :_wakeup, :wakeup
+
+      # Releases the lock and sleeps `timeout` seconds if it is given and non-nil or forever.
+      # Raises MutexError if mutex wasn’t locked by the current owner.
+      # Raises MutexTimeout if #block_timeout= was set and timeout
+      # occured while locking after sleep.
+      # If code block is provided it is executed after waking up, just before grabbing a lock.
+      def sleep(timeout = nil)
+        raise MutexError, "can't sleep #{self.class} wasn't locked" unless unlock!
+        start = Time.now
+        current = Fiber.current
+        @slept[current] = true
+        if timeout
+          timer = ::EM.add_timer(timeout) do
+            wakeup(current)
           end
+          Fiber.yield
+          ::EM.cancel_timer timer
+        else
+          Fiber.yield
         end
-        true
-      ensure
-        timer.cancel if timer
-        timer = nil
-        queues.each {|q| q.delete handler }
-        names.each {|n| @@signal_queue.delete(n) if @@signal_queue[n].empty? }
+        @slept.delete current
+        yield if block_given?
+        raise MutexTimeout unless lock
+        Time.now - start
       end
 
       # Execute block of code protected with semaphore.
@@ -288,7 +358,7 @@ class Redis
       # If `block_timeout` or Mutex#block_timeout is set and
       # lock isn't obtained within `block_timeout` seconds this method raises
       # MutexTimeout.
-      def synchronize(block_timeout = nil)
+      def synchronize(block_timeout=nil)
         if lock(block_timeout)
           begin
             yield self
@@ -300,18 +370,27 @@ class Redis
         end
       end
 
+      # Returns true if watcher is connected
+      def watching?; @@watching == $$; end
+
+      # Returns true if watcher is connected
+      def self.watching?; @@watching == $$; end
+
       class << self
         def ns; @@ns; end
         def ns=(namespace); @@ns = namespace; end
         alias_method :namespace, :ns
         alias_method :'namespace=', :'ns='
-        
+
         # Default value of expiration timeout in seconds.
         def default_expire; @@default_expire; end
-        
+
         # Assigns default value of expiration timeout in seconds.
         # Must be > 0.
-        def default_expire=(value); @@default_expire=value.to_f.abs; end
+        def default_expire=(value)
+          raise ArgumentError, "#{name}.default_expire value must be greater than 0" unless (value = value.to_f) > 0
+          @@default_expire = value
+        end
 
         # Setup redis database and other defaults
         # MUST BE called once before any semaphore is created.
@@ -414,8 +493,8 @@ class Redis
         # Mutex.setup for "lightweight" startup procedure.
         def start_watcher
           raise MutexError, "call #{self.class}::setup first" unless @@redis_watcher
-          return if @@watching == $$
-          if @@watching
+          return if watching?
+          if @@watching # Process id changed, we've been forked alive!
             @@redis_watcher = Redis.new @redis_options
             @@signal_queue.clear
           end
@@ -456,16 +535,17 @@ class Redis
               else
                 sleep retries > 1 ? 1 : 0.1
               end
-            end while @@watching == $$
+            end while watching?
           end.resume
           until @@watcher_subscribed
-            raise MutexError, "Can not establish watcher channel connection!" unless @@watching == $$
+            raise MutexError, "Can not establish watcher channel connection!" unless watching?
             fiber = Fiber.current
             ::EM.next_tick { fiber.resume }
             Fiber.yield
           end
         end
 
+        # EM sleep helper
         def sleep(seconds)
           fiber = Fiber.current
           ::EM::Timer.new(secs) { fiber.resume }
@@ -480,7 +560,7 @@ class Redis
         # Pass `true` to forcefully stop it. This might instead cause
         # MutexError to be raised in waiting fibers.
         def stop_watcher(force = false)
-          return unless @@watching == $$
+          return unless watching?
           raise MutexError, "call #{self.class}::setup first" unless @@redis_watcher
           unless @@signal_queue.empty? || force
             raise MutexError, "can't stop: active signal queue handlers"
@@ -504,14 +584,16 @@ class Redis
         end
 
         # Attempts to grab the lock and waits if it isn’t available.
-        # Raises MutexError if mutex was locked by the current owner.
+        # Raises MutexError if mutex was locked by the current owner
+        # or if used before Mutex.setup.
+        # Raises ArgumentError on invalid options.
         # Returns instance of Redis::EM::Mutex if lock was successfully obtained.
         # Returns `nil` if lock wasn't available within `:block` seconds.
         #
-        #   Redis::EM::Mutex.lock(*names, opts = {})
+        #   Redis::EM::Mutex.lock(*names, options = {})
         #
         # - *names = lock identifiers - if none they are auto generated
-        # - opts = options hash:
+        # - options = hash:
         # - :name - same as name (in case *names arguments were omitted)
         # - :block - block timeout
         # - :expire - expire timeout (see: Mutex#lock and Mutex#try_lock)
@@ -520,13 +602,14 @@ class Redis
           mutex = new(*args)
           mutex if mutex.lock
         end
+
         # Execute block of code protected with named semaphore.
         # Returns result of code block.
         #
-        #   Redis::EM::Mutex.synchronize(*names, opts = {}, &block)
+        #   Redis::EM::Mutex.synchronize(*names, options = {}, &block)
         # 
         # - *names = lock identifiers - if none they are auto generated
-        # - opts = options hash:
+        # - options = hash:
         # - :name - same as name (in case *names arguments were omitted)
         # - :block - block timeout
         # - :expire - expire timeout (see: Mutex#lock and Mutex#try_lock)
@@ -534,13 +617,13 @@ class Redis
         # 
         # If `:block` is set and lock isn't obtained within `:block` seconds this method raises
         # MutexTimeout.
+        # Raises MutexError if used before Mutex.setup.
+        # Raises ArgumentError on invalid options.
         def synchronize(*args, &block)
           new(*args).synchronize(&block)
         end
       end
 
-      private
-
       def owner_ident(lock_id = nil)
         if lock_id
           "#@@uuid$#$$@#{Fiber.current.__id__} #{lock_id}"