redis-read-write-locks 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9401651786ff69991b9b975ebbc62cf0442fd3f2639c79fad803fab00f335e
-  data.tar.gz: 724513d599b3a614e43a3be6b634ad52c1d64035c63ddfb1566e2c93d4a837a6
+  metadata.gz: c9e310b7b077bb24539719d830b79839dde4f00dc0634d4a2ccbb9e91809105a
+  data.tar.gz: fffb72914195bd66e69ebb800fb0a2fe5bb0a39b79b3d73e912335e4fc968ce3
 SHA512:
-  metadata.gz: be039491564babb54c6e1b5ce87e880bc643f4f761efa24faadbc9c2a890e019c48daac13ebbd83409b0db60885b21e23b53fa7fc2d83a879662690fafab2b2a
-  data.tar.gz: 765be840a9d1abba171df6cee27dc3c775eac4ad8edfdf38eebbc32c21a09e51912713ae7006d6863fc9ff8d6e6299dd1820be503231443169ebb36db62530b0
+  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
-    RETRY_INTERVAL = 0.01
+    DEFAULT_RETRY_DELAY = 100
+    PENDING_WRITER_TTL = 30_000
 
     attr_reader :name, :token
 
@@ -19,35 +22,73 @@ module RedisReadWriteLocks
       @acquired
     end
 
-    # Non-blocking: returns true/false.
-    # With timeout: retries for timeout milliseconds, returns true or raises LockTimeoutError.
-    def acquire(timeout: nil)
-      return try_acquire if timeout.nil?
+    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
 
-      deadline = Time.now.to_f + timeout / 1000.0
-      loop do
+      retry_count.times do
+        sleep retry_delay / 1000.0
         return true if try_acquire
-        raise LockTimeoutError, "Timeout acquiring #{lock_type} lock '#{@name}'" if Time.now.to_f >= deadline
-        sleep RETRY_INTERVAL
+      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
 
-    # Acquires lock, yields, releases. Raises LockNotAcquiredError if non-blocking acquire fails.
-    def synchronize(timeout: nil, &block)
-      if timeout
-        acquire(timeout: timeout)
-      else
-        acquire || raise(LockNotAcquiredError, "Could not acquire #{lock_type} lock '#{@name}'")
-      end
+    WATCHDOG_REFRESH_INTERVAL = 10
+    WATCHDOG_SLEEP_INTERVAL = 0.5
+
+    def synchronize(retry_count: nil, retry_delay: DEFAULT_RETRY_DELAY, &block)
+      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
@@ -56,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)
@@ -5,14 +7,15 @@ module RedisReadWriteLocks
       @default_ttl = default_ttl
     end
 
-    def read_lock(name, ttl: @default_ttl, timeout: nil, &block)
+    def read_lock(name, ttl: @default_ttl, retry_count: nil, retry_delay: BaseLock::DEFAULT_RETRY_DELAY, &block)
       lock = ReadLock.new(redis: @redis, name: name, ttl: ttl)
-      block ? lock.synchronize(timeout: timeout, &block) : lock
+      block ? lock.synchronize(retry_count: retry_count, retry_delay: retry_delay, &block) : lock
     end
 
-    def write_lock(name, ttl: @default_ttl, timeout: nil, &block)
-      lock = WriteLock.new(redis: @redis, name: name, ttl: ttl)
-      block ? lock.synchronize(timeout: timeout, &block) : lock
+    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
 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.3.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.3.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: