redis-em-mutex 0.1.2 → 0.2.0

data/HISTORY.rdoc

@@ -1,3 +1,12 @@
+0.2.0
+- added compatibility with EM::Synchrony::Thread::ConditionVariable
+- added #sleep and #wakeup
+- moved Redis::EM::Mutex::NS to autoloaded file
+- added #unlock! and now mutex object stores ownership information
+- added #expired? and other expiration status methods
+- added watching? helper
+- added customizable ownership
+
 0.1.2
 - features macro-style definitions
 - fixed: setup with :redis

data/README.rdoc

@@ -18,9 +18,11 @@ Author::    Rafał Michalski  (mailto:rafal@yeondir.com)
   multiple semaphores are required to be locked at once)
 * best served with EM-Synchrony (uses EM::Synchrony::ConnectionPool internally)
 * fiber-safe
-* deadlock detection (only trivial cases: locking twice the same resource from the same fiber)
+* deadlock detection (only trivial cases: locking twice the same resource from the same owner)
 * mandatory lock expiration (with refreshing)
 * macro-style definitions (Mutex::Macro mixin)
+* compatible with Synchrony::Thread::ConditionVariable
+* extendable (beyond fibers) mutex ownership
 
 == BUGS/LIMITATIONS
 
@@ -42,7 +44,7 @@ Author::    Rafał Michalski  (mailto:rafal@yeondir.com)
 
 ==== Gemfile
 
-  gem "redis-em-mutex", "~> 0.1.2"
+  gem "redis-em-mutex", "~> 0.2.0"
 
 ==== Github
 
@@ -189,8 +191,96 @@ The locking scope will be Mutex global namespace + class name + method name.
 
   end
 
+=== ConditionVariable
+
+Redis::EM::Mutex may be used with EventMachine::Synchrony::Thread::ConditionVariable
+in place of EventMachine::Synchrony::Thread::Mutex.
+
+  mutex = Redis::EM::Mutex.new('resource')
+  resource = EM::Synchrony::Thread::ConditionVariable.new
+  EM::Synchrony.next_tick do
+    mutex.synchronize {
+      # current fiber now needs the resource
+      resource.wait(mutex)
+      # current fiber can now have the resource
+    }
+  end
+  EM::Synchrony.next_tick do
+    mutex.synchronize {
+      # current fiber has finished using the resource
+      resource.signal
+    }
+  end
+
 === Advanced
 
+==== Customized owner
+
+In some cases you might want to extend the ownership of a locked semaphore beyond the current fiber.
+That is to be able to "share" a locked semaphore between group of fibers associated with some external resource.
+
+For example we want to allow only one connection from one ip address to be made to our group of servers
+at the same time.
+Of course you could configure some kind of load balancer that distributes your load to do that for you,
+but let's just assume that the load balancer has no such features available.
+
+The default "owner" of a locked semaphore consists of 3 parts: "Machine uuid" + "process pid" + "fiber id".
+Redis::EM::Mutex allows you to replace the last part of the "owner" with your own value.
+To customize mutex's "ownership" you should add :owner option to the created mutex,
+passing some well defined owner id.
+In our case the "scope" of a mutex will be the client's ip address and the "owner id"
+will be an __id__ of an EventMachine::Connection object created upon connection from the client.
+This way we make sure that any other connection from the same ip address made to any server and process
+will have different ownership defined. At the same time all the fibers working with that Connection instance
+can access mutex's #refresh and #unlock methods concurrently.
+
+  module MutexedConnection
+    def post_init
+      @buffer = ""
+      @mutex = nil
+      ip = Socket.unpack_sockaddr_in(get_peername).last
+      Fiber.new do
+        @mutex = Redis::EM::Mutex.lock(ip, block: 0, owner: self.__id__)
+        if @mutex
+          send_data "Hello #{ip}!"
+          #... initialize stuff
+        else
+          send_data "Duplicate connection not allowed!"
+          close_connection_after_writing
+        end
+      end.resume
+    end
+
+    def unbind
+      if @mutex
+        Fiber.new { @mutex.unlock! }.resume
+      end
+    end
+
+    def receive_data(data)
+      @buffer << data
+      return unless @mutex
+      Fiber.new do
+        if @mutex.refresh # refresh expiration timeout
+          # ... handle data
+        else
+          close_connection_after_writing
+        end
+      end.resume
+    end
+  end
+
+  EM::Synchrony.run {
+    Redis::EM::Mutex.setup(size: 10, url: 'redis:///1', expire: 600)
+    EM.start_server "0.0.0.0", 6969, MutexedConnection
+  }
+
+==== Forking live
+
+You may safely fork process while running event reactor and having locked semaphores.
+The locked semaphores in newly forked process will become unlocked while
+their locked status in parent process will be preserved.
+
   mutex = Redis::EM::Mutex.new('resource1', 'resource2', expire: 60)
 
   EM.synchrony do

data/lib/redis/em-mutex/ns.rb

@@ -0,0 +1,47 @@
+class Redis
+  module EM
+    class Mutex
+      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
+
+        # 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
+
+        # Executes block of code protected with namespaced semaphore.
+        #
+        # See: Redis::EM::Mutex.synchronize
+        def synchronize(*args, &block)
+          new(*args).synchronize(&block)
+        end
+      end
+    end
+  end
+end

data/lib/redis/em-mutex/version.rb

@@ -1,7 +1,7 @@
 class Redis
   module EM
     class Mutex
-      VERSION = '0.1.2'
+      VERSION = '0.2.0'
     end
   end
 end