redis-read-write-locks 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf0e4824a200a3a7edd4b4dfe626ebfb8cb243b69ed87ebeba49f8e545067708
-  data.tar.gz: 24165395045c8fb6ab49d243beeb711d693efbbb79d709b4bb680e6a94947566
+  metadata.gz: c9e310b7b077bb24539719d830b79839dde4f00dc0634d4a2ccbb9e91809105a
+  data.tar.gz: fffb72914195bd66e69ebb800fb0a2fe5bb0a39b79b3d73e912335e4fc968ce3
 SHA512:
-  metadata.gz: 93156958fcdb655a7539aa1dc00f5d2ba8a287d374f3eedd65352bff7af1ac27a031058d1bba1db04afa8c99af72bde2ca9c2763797ddb48f2d0fd5bf839bea8
-  data.tar.gz: be70fc26075e27252d6070c1770ad1aa0ca8cdfece6b85aa6ac226db41d522878a4d0aebb847535da029666f2f778ddb6f51ac69a43cffcc2d8891b32eaea4c2
+  metadata.gz: 1d1f9430aa04d71be97759004e36786de7f99aa845b6379d776718fc9adac65c486765a2ce6096ff4a22d4c273f14c5d40b4c128b782071b0a80c4ed4fc1fae3
+  data.tar.gz: 03a01ad0f6fa2906d2934fcdc23ae12bef0b77448936de949d7422c61d6ec98d004b58648e31517e1edf5466ed6a33633958b92e6bb9ab6c28e885a2011f053e

data/README.md

@@ -49,6 +49,7 @@ client = RedisReadWriteLocks::Client.new(redis, default_ttl: 60_000)
 | Option | Default | Description |
 |--------|---------|-------------|
 | `ttl`  | `30`    | Lock TTL in seconds. Lock auto-expires if holder crashes. |
+| `prefer_writer` | `false` | Write lock only. When `true`, a writer blocked on acquire registers its intent so new readers are refused until it acquires or gives up. Only takes effect when `retry_count` is set — a non-retrying writer isn't waiting, so it registers and immediately clears its intent, making the flag a no-op. |
 
 ### Errors
 
@@ -60,8 +61,10 @@ client = RedisReadWriteLocks::Client.new(redis, default_ttl: 60_000)
 ## Redis key structure
 
 ```
-rw_lock:writer:<name>   # String, holds owner token, TTL = lock TTL
-rw_lock:readers:<name>  # Sorted set, member = token, score = expiry timestamp
+rw_lock:writer:<name>           # String, holds owner token, TTL = lock TTL
+rw_lock:readers:<name>          # Sorted set, member = token, score = expiry timestamp
+rw_lock:pending_writers:<name>  # Sorted set, member = token, score = pending-intent expiry timestamp.
+                                 # Populated only by writers using `prefer_writer: true`.
 ```
 
 ## Requirements

data/lib/redis-read-write-locks.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require_relative "redis_read_write_locks"

data/lib/redis_read_write_locks/base_lock.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require "securerandom"
 
 module RedisReadWriteLocks
   class BaseLock
     DEFAULT_TTL = 30_000
     DEFAULT_RETRY_DELAY = 100
+    PENDING_WRITER_TTL = 30_000
 
     attr_reader :name, :token
 
@@ -20,31 +23,72 @@ module RedisReadWriteLocks
     end
 
     def acquire(retry_count: nil, retry_delay: DEFAULT_RETRY_DELAY)
+      @retry_delay = retry_count.nil? ? 0 : retry_delay
+
       return try_acquire if retry_count.nil?
 
       return true if try_acquire
+
       retry_count.times do
         sleep retry_delay / 1000.0
         return true if try_acquire
       end
       raise LockTimeoutError, "Could not acquire #{lock_type} lock '#{@name}' after #{retry_count} retries"
+    ensure
+      begin
+        abandon_pending unless acquired?
+      rescue StandardError
+        nil
+      end
     end
 
+    WATCHDOG_REFRESH_INTERVAL = 10
+    WATCHDOG_SLEEP_INTERVAL = 0.5
+
     def synchronize(retry_count: nil, retry_delay: DEFAULT_RETRY_DELAY, &block)
-      if retry_count
-        acquire(retry_count: retry_count, retry_delay: retry_delay)
-      else
-        acquire || raise(LockNotAcquiredError, "Could not acquire #{lock_type} lock '#{@name}'")
-      end
+      acquire_or_raise(retry_count: retry_count, retry_delay: retry_delay)
+      stopped = false
+      watchdog = start_watchdog(Thread.current, -> { stopped })
       begin
         block.call
       ensure
+        stopped = true
+        watchdog.join
         release
       end
     end
 
     private
 
+    def acquire_or_raise(retry_count:, retry_delay:)
+      return acquire(retry_count: retry_count, retry_delay: retry_delay) if retry_count
+
+      acquire || raise(LockNotAcquiredError, "Could not acquire #{lock_type} lock '#{@name}'")
+    end
+
+    def start_watchdog(main_thread, stopped)
+      Thread.new do
+        elapsed = 0.0
+        until stopped.call
+          sleep WATCHDOG_SLEEP_INTERVAL
+          elapsed += WATCHDOG_SLEEP_INTERVAL
+          next if stopped.call
+          next unless elapsed >= WATCHDOG_REFRESH_INTERVAL
+
+          elapsed = 0.0
+          begin
+            unless refresh
+              main_thread.raise(LockRefreshError, "Could not refresh #{lock_type} lock '#{@name}'")
+              break
+            end
+          rescue StandardError => e
+            main_thread.raise(e)
+            break
+          end
+        end
+      end
+    end
+
     def writer_key
       "rw_lock:writer:#{@name}"
     end
@@ -53,6 +97,14 @@ module RedisReadWriteLocks
       "rw_lock:readers:#{@name}"
     end
 
+    def pending_writers_key
+      "rw_lock:pending_writers:#{@name}"
+    end
+
+    def abandon_pending
+      nil
+    end
+
     def lock_type
       self.class.name.split("::").last.sub("Lock", "").downcase
     end

data/lib/redis_read_write_locks/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
   class Client
     def initialize(redis, default_ttl: BaseLock::DEFAULT_TTL)
@@ -10,8 +12,9 @@ module RedisReadWriteLocks
       block ? lock.synchronize(retry_count: retry_count, retry_delay: retry_delay, &block) : lock
     end
 
-    def write_lock(name, ttl: @default_ttl, retry_count: nil, retry_delay: BaseLock::DEFAULT_RETRY_DELAY, &block)
-      lock = WriteLock.new(redis: @redis, name: name, ttl: ttl)
+    def write_lock(name, ttl: @default_ttl, retry_count: nil, retry_delay: BaseLock::DEFAULT_RETRY_DELAY,
+                   prefer_writer: false, &block)
+      lock = WriteLock.new(redis: @redis, name: name, ttl: ttl, prefer_writer: prefer_writer)
       block ? lock.synchronize(retry_count: retry_count, retry_delay: retry_delay, &block) : lock
     end
   end

data/lib/redis_read_write_locks/errors.rb

@@ -1,5 +1,15 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
-  Error = Class.new(StandardError)
-  LockNotAcquiredError = Class.new(Error)
-  LockTimeoutError = Class.new(Error)
+  class Error < StandardError
+  end
+
+  class LockNotAcquiredError < Error
+  end
+
+  class LockTimeoutError < Error
+  end
+
+  class LockRefreshError < Error
+  end
 end

data/lib/redis_read_write_locks/lock_scripts.rb

@@ -1,26 +1,35 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
   module LockScripts
-    # KEYS[1] = writer_key, KEYS[2] = readers_key
-    # ARGV[1] = token, ARGV[2] = expiry (unix ts), ARGV[3] = now (unix ts)
+    # KEYS[1] = writer_key, KEYS[2] = readers_key, KEYS[3] = pending_writers_key
+    # ARGV[1] = token, ARGV[2] = expiry (unix ts), ARGV[3] = now (unix ts), ARGV[4] = ttl (ms)
     # Returns 1 = acquired, 0 = blocked
-    ACQUIRE_READ = <<~LUA.freeze
+    ACQUIRE_READ = <<~LUA
       local writer_key = KEYS[1]
       local readers_key = KEYS[2]
+      local pending_writers_key = KEYS[3]
       local token = ARGV[1]
       local expiry = tonumber(ARGV[2])
       local now = tonumber(ARGV[3])
+      local ttl_ms = tonumber(ARGV[4])
 
       redis.call('ZREMRANGEBYSCORE', readers_key, '-inf', now)
+      redis.call('ZREMRANGEBYSCORE', pending_writers_key, '-inf', now)
 
       if redis.call('EXISTS', writer_key) == 1 then
         return 0
       end
 
+      if redis.call('ZCARD', pending_writers_key) > 0 then
+        return 0
+      end
+
       redis.call('ZADD', readers_key, expiry, token)
 
-      local current_ttl = redis.call('TTL', readers_key)
-      if current_ttl == -1 or (current_ttl > 0 and (now + current_ttl) < expiry) then
-        redis.call('EXPIREAT', readers_key, expiry + 1)
+      local current_pttl = redis.call('PTTL', readers_key)
+      if current_pttl == -1 or current_pttl < ttl_ms then
+        redis.call('PEXPIRE', readers_key, ttl_ms)
       end
 
       return 1
@@ -28,44 +37,100 @@ module RedisReadWriteLocks
 
     # KEYS[1] = readers_key
     # ARGV[1] = token
-    RELEASE_READ = <<~LUA.freeze
+    RELEASE_READ = <<~LUA
       redis.call('ZREM', KEYS[1], ARGV[1])
       return 1
     LUA
 
-    # KEYS[1] = writer_key, KEYS[2] = readers_key
-    # ARGV[1] = token, ARGV[2] = ttl (seconds), ARGV[3] = now (unix ts)
+    # KEYS[1] = writer_key, KEYS[2] = readers_key, KEYS[3] = pending_writers_key
+    # ARGV[1] = token, ARGV[2] = ttl (ms), ARGV[3] = now (unix ts),
+    # ARGV[4] = prefer (1 = writer preference on), ARGV[5] = pending expiry (unix ts),
+    # ARGV[6] = pending ttl (ms)
     # Returns 1 = acquired, 0 = blocked
-    ACQUIRE_WRITE = <<~LUA.freeze
+    ACQUIRE_WRITE = <<~LUA
       local writer_key = KEYS[1]
       local readers_key = KEYS[2]
+      local pending_writers_key = KEYS[3]
       local token = ARGV[1]
       local ttl = tonumber(ARGV[2])
       local now = tonumber(ARGV[3])
+      local prefer = tonumber(ARGV[4])
+      local pending_expiry = tonumber(ARGV[5])
+      local pending_ttl_ms = tonumber(ARGV[6])
 
       redis.call('ZREMRANGEBYSCORE', readers_key, '-inf', now)
+      redis.call('ZREMRANGEBYSCORE', pending_writers_key, '-inf', now)
 
-      if redis.call('ZCARD', readers_key) > 0 then
-        return 0
-      end
+      if redis.call('ZCARD', readers_key) > 0 or redis.call('EXISTS', writer_key) == 1 then
+        if prefer == 1 then
+          redis.call('ZADD', pending_writers_key, pending_expiry, token)
+
+          local current_pttl = redis.call('PTTL', pending_writers_key)
+          if current_pttl == -1 or current_pttl < pending_ttl_ms then
+            redis.call('PEXPIRE', pending_writers_key, pending_ttl_ms)
+          end
+        end
 
-      if redis.call('EXISTS', writer_key) == 1 then
         return 0
       end
 
-      redis.call('SET', writer_key, token, 'EX', ttl)
+      redis.call('SET', writer_key, token, 'PX', ttl)
+      redis.call('ZREM', pending_writers_key, token)
       return 1
     LUA
 
     # KEYS[1] = writer_key
     # ARGV[1] = token
     # Returns 1 = released, 0 = not owner
-    RELEASE_WRITE = <<~LUA.freeze
+    RELEASE_WRITE = <<~LUA
       if redis.call('GET', KEYS[1]) == ARGV[1] then
         redis.call('DEL', KEYS[1])
         return 1
       end
       return 0
     LUA
+
+    # KEYS[1] = pending_writers_key
+    # ARGV[1] = token
+    # Returns 1 = cleared
+    CLEAR_PENDING_WRITE = <<~LUA
+      redis.call('ZREM', KEYS[1], ARGV[1])
+      return 1
+    LUA
+
+    # KEYS[1] = writer_key
+    # ARGV[1] = token, ARGV[2] = ttl (milliseconds)
+    # Returns 1 = refreshed, 0 = not owner
+    REFRESH_WRITE = <<~LUA
+      if redis.call('GET', KEYS[1]) == ARGV[1] then
+        redis.call('PEXPIRE', KEYS[1], ARGV[2])
+        return 1
+      end
+      return 0
+    LUA
+
+    # KEYS[1] = readers_key
+    # ARGV[1] = token, ARGV[2] = expiry (unix ts), ARGV[3] = now (unix ts), ARGV[4] = ttl (ms)
+    # Returns 1 = refreshed, 0 = not in set
+    REFRESH_READ = <<~LUA
+      local readers_key = KEYS[1]
+      local token = ARGV[1]
+      local expiry = tonumber(ARGV[2])
+      local now = tonumber(ARGV[3])
+      local ttl_ms = tonumber(ARGV[4])
+
+      if redis.call('ZSCORE', readers_key, token) == false then
+        return 0
+      end
+
+      redis.call('ZADD', readers_key, expiry, token)
+
+      local current_pttl = redis.call('PTTL', readers_key)
+      if current_pttl == -1 or current_pttl < ttl_ms then
+        redis.call('PEXPIRE', readers_key, ttl_ms)
+      end
+
+      return 1
+    LUA
   end
 end

data/lib/redis_read_write_locks/read_lock.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
   class ReadLock < BaseLock
     def release
@@ -8,16 +10,24 @@ module RedisReadWriteLocks
       true
     end
 
+    def refresh
+      return false unless @acquired
+
+      now = Time.now.to_i
+      expiry = now + (@ttl / 1000.0).ceil
+      eval_script(LockScripts::REFRESH_READ, keys: [readers_key], argv: [@token, expiry, now, @ttl]) == 1
+    end
+
     private
 
     def try_acquire
       now = Time.now.to_i
-      expiry = now + @ttl / 1000
+      expiry = now + (@ttl / 1000.0).ceil
 
       result = eval_script(
         LockScripts::ACQUIRE_READ,
-        keys: [writer_key, readers_key],
-        argv: [@token, expiry, now],
+        keys: [writer_key, readers_key, pending_writers_key],
+        argv: [@token, expiry, now, @ttl]
       )
 
       @acquired = result == 1

data/lib/redis_read_write_locks/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/redis_read_write_locks/write_lock.rb

@@ -1,5 +1,12 @@
+# frozen_string_literal: true
+
 module RedisReadWriteLocks
   class WriteLock < BaseLock
+    def initialize(redis:, name:, ttl: DEFAULT_TTL, prefer_writer: false)
+      super(redis: redis, name: name, ttl: ttl)
+      @prefer_writer = prefer_writer
+    end
+
     def release
       return false unless @acquired
 
@@ -8,16 +15,34 @@ module RedisReadWriteLocks
       true
     end
 
+    def refresh
+      return false unless @acquired
+
+      eval_script(LockScripts::REFRESH_WRITE, keys: [writer_key], argv: [@token, @ttl]) == 1
+    end
+
     private
 
     def try_acquire
+      now = Time.now.to_i
+      pending_ttl_ms = [PENDING_WRITER_TTL, @retry_delay.to_i * 3].max
+      pending_expiry = now + (pending_ttl_ms / 1000.0).ceil
+
       result = eval_script(
         LockScripts::ACQUIRE_WRITE,
-        keys: [writer_key, readers_key],
-        argv: [@token, @ttl / 1000, Time.now.to_i],
+        keys: [writer_key, readers_key, pending_writers_key],
+        argv: [
+          @token, @ttl, now, @prefer_writer ? 1 : 0, pending_expiry, pending_ttl_ms
+        ]
       )
 
       @acquired = result == 1
     end
+
+    def abandon_pending
+      return unless @prefer_writer
+
+      eval_script(LockScripts::CLEAR_PENDING_WRITE, keys: [pending_writers_key], argv: [@token])
+    end
   end
 end

data/lib/redis_read_write_locks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "redis_read_write_locks/version"
 require_relative "redis_read_write_locks/errors"
 require_relative "redis_read_write_locks/lock_scripts"

data/redis-read-write-locks.gemspec

@@ -18,4 +18,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "redis-client"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-read-write-locks
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Umbrellio
@@ -65,6 +65,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Redis-backed distributed read-write locks. Multiple concurrent readers,
   exclusive writers.
 email: