redis-em-mutex 0.2.3 → 0.3.0

data/BENCHMARK.md

@@ -0,0 +1,134 @@
+BENCHMARK
+=========
+
+To measure the performance of {Redis::EM::Mutex} I've wrote a simple script called `benchmark_mutex.rb`.
+The script is included in respository.
+
+Below are the results of running tests against the following versions:
+
+- redis-em-mutex v0.1.2
+- redis-em-mutex v0.2.3
+- redis-em-mutex v0.3.0 - "pure" handler
+- redis-em-mutex v0.3.0 - "script" handler
+
+To run theese tests type:
+
+```sh
+cp benchmark_mutex.rb /tmp/
+
+git reset --hard v0.1.2
+ruby /tmp/benchmark_mutex.rb
+
+git reset --hard v0.2.3
+ruby /tmp/benchmark_mutex.rb
+
+git reset --hard v0.3.0
+REDIS_EM_MUTEX_HANDLER=pure ruby benchmark_mutex.rb
+REDIS_EM_MUTEX_HANDLER=script ruby benchmark_mutex.rb
+```
+
+Here are the results of running those tests on Quad Core Xeon machine
+with redis-server 2.6.9 and ruby 1.9.3p374 (2013-01-15 revision 38858) [x86_64-linux].
+
+The results may vary.
+
+Test 1
+======
+
+Lock/unlock 1000 times using 10 concurrent fibers.
+
+```
+Version: 0.1.2, handler: N/A
+lock/unlock 1000 times with concurrency: 10
+                    user     system      total        real
+keys: 1         0.590000   0.220000   0.810000 (  1.124918)
+keys: 2         0.640000   0.220000   0.860000 (  1.214577)
+keys: 3         0.660000   0.200000   0.860000 (  1.245093)
+keys: 5         0.770000   0.140000   0.910000 (  1.322475)
+keys:10         0.890000   0.210000   1.100000 (  1.456293)
+
+Version: 0.2.3, handler: N/A
+lock/unlock 1000 times with concurrency: 10
+                    user     system      total        real
+keys: 1         0.640000   0.200000   0.840000 (  1.105686)
+keys: 2         1.090000   0.420000   1.510000 (  2.014079)
+keys: 3         1.450000   0.500000   1.950000 (  2.738510)
+keys: 5         1.940000   0.820000   2.760000 (  4.136856)
+keys:10         3.360000   1.900000   5.260000 (  8.232977)
+
+Version: 0.3.0, handler: Redis::EM::Mutex::PureHandlerMixin
+lock/unlock 1000 times with concurrency: 10
+                    user     system      total        real
+keys: 1         0.610000   0.230000   0.840000 (  0.864242)
+keys: 2         0.640000   0.220000   0.860000 (  0.914122)
+keys: 3         0.660000   0.260000   0.920000 (  0.947300)
+keys: 5         0.730000   0.250000   0.980000 (  1.007862)
+keys:10         0.840000   0.230000   1.070000 (  1.315885)
+
+Version: 0.3.0, handler: Redis::EM::Mutex::ScriptHandlerMixin
+lock/unlock 1000 times with concurrency: 10
+                    user     system      total        real
+keys: 1         0.290000   0.110000   0.400000 (  0.633668)
+keys: 2         0.280000   0.150000   0.430000 (  0.714378)
+keys: 3         0.290000   0.100000   0.390000 (  0.657861)
+keys: 5         0.430000   0.100000   0.530000 (  0.775208)
+keys:10         0.330000   0.150000   0.480000 (  0.904942)
+```
+
+Test 2
+======
+
+run 100 fibers which will repeat the following actions:
+
+- sleep some predefined time
+- lock
+- write some value to redis key
+- increase value in redis key
+- read value from that key
+- delete that key
+- unlock
+
+Wait 5 seconds and then tell all the fibers to quit.
+The wall time also includes the "cooling time" which lasted
+after 5 seconds has elapsed to the moment where all the fibers
+have ceased processing.
+The resulting value is how many times the above actions were repeated
+during that period.
+
+```
+Version: 0.1.2, handler: N/A
+lock/write/incr/read/del/unlock in 5 seconds + cooldown period:
+        result      user     system      total        real
+keys: 1   3256  2.290000   1.230000   3.520000 (  5.135926)
+keys: 2   3179  2.260000   1.000000   3.260000 (  5.124043)
+keys: 3   3072  2.160000   1.170000   3.330000 (  5.128032)
+keys: 5   2859  2.280000   1.070000   3.350000 (  5.132027)
+keys:10   2564  2.460000   0.860000   3.320000 (  5.151968)
+
+Version: 0.2.3, handler: N/A
+lock/write/incr/read/del/unlock in 5 seconds + cooldown period:
+        result      user     system      total        real
+keys: 1   3274  2.480000   1.010000   3.490000 (  5.111753)
+keys: 2   2429  2.740000   1.270000   4.010000 (  5.204065)
+keys: 3   1855  2.380000   1.210000   3.590000 (  5.256041)
+keys: 5   1309  2.890000   1.250000   4.140000 (  5.376043)
+keys:10    710  3.120000   1.190000   4.310000 (  5.763981)
+
+Version: 0.3.0, handler: Redis::EM::Mutex::PureHandlerMixin
+lock/write/incr/read/del/unlock in 5 seconds + cooldown period:
+        result  user     system      total        real
+keys: 1   3795  2.490000   1.400000   3.890000 (  5.108474)
+keys: 2   3788  2.600000   1.400000   4.000000 (  5.108037)
+keys: 3   3921  2.800000   1.170000   3.970000 (  5.120059)
+keys: 5   3641  2.820000   1.140000   3.960000 (  5.112036)
+keys:10   2661  2.860000   1.130000   3.990000 (  5.152105)
+
+Version: 0.3.0, handler: Redis::EM::Mutex::ScriptHandlerMixin
+lock/write/incr/read/del/unlock in 5 seconds + cooldown period:
+        result   user     system      total        real
+keys: 1   5177  1.980000   1.020000   3.000000 (  5.079791)
+keys: 2   5460  1.600000   1.030000   2.630000 (  5.080049)
+keys: 3   5322  1.560000   1.000000   2.560000 (  5.088010)
+keys: 5   4685  1.620000   0.810000   2.430000 (  5.084035)
+keys:10   4347  1.600000   0.770000   2.370000 (  5.111976)
+```

data/{HISTORY.rdoc → HISTORY.md}

@@ -1,5 +1,14 @@
+0.3.0
+- fixed: optimized pure handler
+- added redis/em-connection-pool no more em-synchrony/connection_pool dependency
+- added redis gem dependency updated to 3.0.2
+- added owner_ident specs
+- added redis-lua script handler
+- added #can_refresh_expired? handler feature detection
+- added handlers
+
 0.2.3
-- fixed: rare but possible race condition in unlock!
+- fixed: rare unlock! race condition introduced in 0.2.1
   manifesting as deadlock exception when no deadlock should occur
 
 0.2.2

data/README.md

@@ -17,9 +17,9 @@ FEATURES
 * no CPU-intensive sleep/polling while waiting for lock to become available
 * fibers waiting for the lock are signalled via Redis channel as soon as the lock
   has been released (~< 1 ms)
+* alternative fast "script" handler (server-side LUA script based - redis-server 2.6.x)
 * multi-locks (all-or-nothing) locking (to prevent possible deadlocks when
   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 owner)
 * mandatory lock expiration (with refreshing)
@@ -39,7 +39,7 @@ REQUIREMENTS
 ------------
 
 * ruby >= 1.9 (tested: ruby 1.9.3p374, 1.9.3-p194, 1.9.2-p320, 1.9.1-p378)
-* http://github.com/redis/redis-rb ~> 3.0.1
+* http://github.com/redis/redis-rb ~> 3.0.2
 * http://rubyeventmachine.com ~> 1.0.0
 * (optional) http://github.com/igrigorik/em-synchrony
 
@@ -53,7 +53,7 @@ $ [sudo] gem install redis-em-mutex
 #### Gemfile
 
 ```ruby
-gem "redis-em-mutex", "~> 0.2.3"
+gem "redis-em-mutex", "~> 0.3.0"
 ```
 
 #### Github
@@ -62,6 +62,27 @@ gem "redis-em-mutex", "~> 0.2.3"
 git clone git://github.com/royaltm/redis-em-mutex.git
 ```
 
+UPGRADING
+---------
+
+0.2.x -> 0.3.x
+
+To upgrade redis-em-mutex on production from 0.2.x to 0.3.x you must make sure the correct handler has been
+selected. See more on HANDLERS below.
+
+The "pure" and "script" handlers are not compatible. Two different handlers must not utilize the same semaphore-key space.
+
+Because only the "pure" handler is compatible with redis-em-mutex <= 0.2.x, when upgrading live production make sure to add
+`handler: :pure` option to `Redis::EM::Mutex.setup` or set the environment variable on production app servers:
+
+```sh
+  REDIS_EM_MUTEX_HANDLER=pure
+  export REDIS_EM_MUTEX_HANDLER
+```
+Upgrading from "pure" to "script" handler requires that all "pure" handler locks __MUST BE DELETED__ from redis-server beforehand.
+Neglecting that will result in possible deadlocks. The "script" handler assumes that the lock expiration process is handled
+by redis-server's PEXPIREAT feature. The "pure" handler does not set timeouts on keys. It handles expiration differently.
+
 USAGE
 -----
 
@@ -107,6 +128,58 @@ USAGE
     end
 ```
 
+### Handlers
+
+There are 2 different mutex implementations since version 0.3.0.
+
+* The "pure" classic handler utilizes redis optimistic transaction commands (watch/multi).
+  This handler works with redis-server 2.4.x and later.
+* The new "script" handler takes advantage of fast atomic server side operations written in LUA.
+  Therefore the "script" handler is compatible only with redis-server 2.6.x and later.
+
+__IMPORTANT__: The "pure" and "script" implementations are not compatible. The values that each handler stores in semaphore keys have different meaning to them.
+You can not operate on the same set of keys using both handlers from e.g. different applications or application versions.
+See UPGRADING for more info on this.
+
+You choose your preferred implementation with `handler` option:
+
+```ruby
+    Redis::EM::Mutex.setup(handler: :script)
+    Redis::EM::Mutex.handler # "Redis::EM::Mutex::ScriptHandlerMixin"
+
+    # or
+
+    Redis::EM::Mutex.setup do |opts|
+      opts.handler = :pure
+    end
+    Redis::EM::Mutex.handler # "Redis::EM::Mutex::PureHandlerMixin"
+```
+
+You may also setup `REDIS_EM_MUTEX_HANDLER` environment variable to preferred implementation name.
+Passing `handler` option to {Redis::EM::Mutex.setup} overrides environment variable.
+
+The default handler option is `auto` which selects best handler available for your redis-server.
+It's good for quick sandbox setup, however you should set explicitly which handler you require on production.
+
+The differences:
+
+* Performance. The "script" handler is faster then the "pure" handler.
+  The "pure" handler generates twice as much CPU load as "script" handler.
+  See {file:BENCHMARK.md BENCHMARK}.
+
+* Expiration. The "script" implementation handler uses PEXPIREAT to mark semaphore life-time.
+  The "pure" handler stores semaphore expiry timestamp in key value.
+  Therefore the "script" handler can't refresh semaphores once they expire.
+  The "pure" handler on the other hand could refresh expired semaphore but only
+  if nothing else has locked on that expired key.
+
+To detect feature of the current handler:
+
+```ruby
+  Redis::EM::Mutex.can_refresh_expired?           # true / false
+  Redis::EM::Mutex.new(:foo).can_refresh_expired? # true / false
+```
+
 ### Namespaces
 
 ```ruby
@@ -128,6 +201,17 @@ USAGE
 
 ### Multi-locks
 
+This feature enables you to lock more then one key at the same time.
+The multi key semaphores are deadlock-safe.
+
+The classic deadlock example scenario with multiple resources:
+
+* A acquires lock on resource :foo
+* B acquires lock on resource :bar
+* A tries to lock on resource :bar still keeping the :foo
+* but at the same time B tries to acquire :foo while keeping the :bar.
+* The deadlock occurs.
+
 ```ruby
   EM.synchrony do
     Redis::EM::Mutex.synchronize('foo', 'bar', 'baz') do
@@ -218,8 +302,8 @@ The locking scope will be Mutex global namespace + class name + method name.
 
 ### ConditionVariable
 
-Redis::EM::Mutex may be used with EventMachine::Synchrony::Thread::ConditionVariable
-in place of EventMachine::Synchrony::Thread::Mutex.
+`Redis::EM::Mutex` may be used with `EventMachine::Synchrony::Thread::ConditionVariable`
+in place of `EventMachine::Synchrony::Thread::Mutex`.
 
 ```ruby
   mutex = Redis::EM::Mutex.new('resource')

data/Rakefile

@@ -5,12 +5,31 @@ task :default => [:test]
 $gem_name = "redis-em-mutex"
 
 desc "Run spec tests"
-task :test do
-  Dir["spec/#{$gem_name}-*.rb"].each do |spec|
-    sh "rspec #{spec}"
+namespace :test do
+
+  task :all => [:auto, :pure, :script]
+
+  task :auto do
+    Dir["spec/#{$gem_name}-*.rb"].each do |spec|
+      sh({'REDIS_EM_MUTEX_HANDLER' => nil}, "rspec #{spec}")
+    end
+  end
+
+  task :pure do
+    Dir["spec/#{$gem_name}-*.rb"].each do |spec|
+      sh({'REDIS_EM_MUTEX_HANDLER' => 'pure'}, "rspec #{spec}")
+    end
+  end
+
+  task :script do
+    Dir["spec/#{$gem_name}-*.rb"].each do |spec|
+      sh({'REDIS_EM_MUTEX_HANDLER' => 'script'}, "rspec #{spec}")
+    end
   end
 end
 
+task :test => [:'test:all']
+
 desc "Build the gem"
 task :gem do
   sh "gem build #$gem_name.gemspec"
@@ -33,5 +52,5 @@ end
 
 desc "Documentation"
 task :doc do
-  sh "yardoc"
+  sh "yardoc - README.md BENCHMARK.md"
 end

data/benchmark_mutex.rb

@@ -0,0 +1,99 @@
+$:.unshift "lib"
+gem 'redis', '~>3.0.2'
+require 'securerandom'
+require 'benchmark'
+require 'em-synchrony'
+require 'em-synchrony/fiber_iterator'
+require 'redis-em-mutex'
+
+RMutex = Redis::EM::Mutex
+include Benchmark
+
+MUTEX_OPTIONS = {
+  expire: 10000,
+  ns: '__Benchmark',
+}
+
+TEST_KEY = '__TEST__'
+
+def assert(condition)
+  raise "Assertion failed: #{__FILE__}:#{__LINE__}" unless condition
+end
+
+# lock and unlock 1000 times
+def test1(keys, concurrency = 10)
+  count = 0
+  mutex = RMutex.new(*keys)
+  EM::Synchrony::FiberIterator.new((1..1000).to_a, concurrency).each do |i|
+    mutex.synchronize { count+=1 }
+  end
+  assert(count == 1000)
+end
+
+# lock, set, incr, read, del, unlock, sleep as many times as possible in 5 seconds
+# the cooldown period will be included in total time
+def test2(keys, redis)
+  running = true
+  count = 0
+  playing = 0
+  mutex = RMutex.new(*keys)
+  f = Fiber.current
+  (1..100).map {|i| i/100000.0+0.001}.shuffle.each do |i|
+    EM::Synchrony.next_tick do
+      while running
+        playing+=1
+        EM::Synchrony.sleep(i)
+        mutex.synchronize do
+          # print "."
+          value = rand(1000000000000000000)
+          redis.set(TEST_KEY, value)
+          redis.incr(TEST_KEY)
+          assert redis.get(TEST_KEY).to_i == value+1
+          redis.del(TEST_KEY)
+          count += 1
+        end
+        playing-=1
+      end
+    end
+  end
+  EM::Synchrony.add_timer(5) do
+    running = false
+    # print "0"
+    EM::Synchrony.sleep(0.001) while playing > 0
+    EM.next_tick { f.resume }
+  end
+  Fiber.yield
+  print '%5d' % count
+end
+
+EM.synchrony do
+  concurrency = 10
+  RMutex.setup(MUTEX_OPTIONS) {|opts| opts.size = concurrency}
+  if RMutex.respond_to? :handler
+    puts "Version: #{RMutex::VERSION}, handler: #{RMutex.handler}"
+  else
+    puts "Version: #{RMutex::VERSION}, handler: N/A"
+  end
+
+  puts "lock/unlock 1000 times with concurrency: #{concurrency}"
+  Benchmark.benchmark(CAPTION, 7, FORMAT) do |x|
+    [1,2,3,5,10].each do |n|
+      keys = n.times.map { SecureRandom.random_bytes + '.lck' }
+      x.report("keys:%2d " % n) { test1(keys, concurrency) }
+      EM::Synchrony.sleep(1)
+    end
+  end
+
+  puts
+  puts "lock/write/incr/read/del/unlock in 5 seconds + cooldown period:"
+  Benchmark.benchmark(CAPTION, 8, FORMAT) do |x|
+    redis = Redis.new
+    [1,2,3,5,10].each do |n|
+      keys = n.times.map { SecureRandom.random_bytes + '.lck' }
+      x.report("keys:%2d " % n) { test2(keys, redis) }
+      EM::Synchrony.sleep(1)
+    end
+  end
+  RMutex.stop_watcher(true)
+  EM.stop
+end

data/lib/redis/em-connection-pool.rb

@@ -0,0 +1,88 @@
+require 'redis'
+class Redis
+  module EM
+    class ConnectionPool
+      def initialize(opts)
+        @pool = []
+        @queue = []
+        @acquired  = {}
+
+        opts[:size].times { @pool << yield }
+      end
+
+      %w[
+        exists
+        setnx
+        publish
+        script
+        msetnx
+        eval
+        evalsha
+      ].each do |name|
+        class_eval <<-EOD, __FILE__, __LINE__
+          def #{name}(*args)
+            execute do |redis|
+              redis.#{name}(*args)
+            end
+          end
+        EOD
+      end
+
+      %w[
+        watch
+        mget
+      ].each do |name|
+        class_eval <<-EOD, __FILE__, __LINE__
+          def #{name}(*args, &blk)
+            execute do |redis|
+              redis.#{name}(*args, &blk)
+            end
+          end
+        EOD
+      end
+
+      def multi(&blk)
+        execute do |redis|
+          redis.multi(&blk)
+        end
+      end
+
+      def execute
+        f = Fiber.current
+        begin
+          until (conn = acquire f)
+            @queue << f
+            Fiber.yield
+          end
+          yield conn
+        ensure
+          release(f)
+        end
+      end
+
+      private
+
+      def acquire(fiber)
+        if conn = @pool.pop
+          @acquired[fiber.__id__] = conn
+          conn
+        end
+      end
+
+      def release(fiber)
+        @pool.push(@acquired.delete(fiber.__id__))
+
+        if queue = @queue.shift
+          queue.resume
+        end
+      end
+
+      def method_missing(method, *args, &blk)
+        execute do |conn|
+          conn.__send__(method, *args, &blk)
+        end
+      end
+    end
+
+  end
+end

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

@@ -27,7 +27,7 @@ class Redis
           Redis::EM::Mutex.new(*args)
         end
 
-        # Attempts to grab the lock and waits if it isn’t available.
+        # Attempts to grab the lock and waits if it isn't available.
         # 
         # See: Redis::EM::Mutex.lock
         def lock(*args)