redis_queued_locks 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4846c7a27c9ce2108903a9b9b9250a38aa18ae34be6da85b4055bfe9c20371bb
-  data.tar.gz: 0346d8a0c4d43490ea0fcf79c7048e70c480285b18f26f84b06ad24fe42dc9fc
+  metadata.gz: 28714dd149659f7c58634868219b3e020df6304253db120fda241304a82ce781
+  data.tar.gz: 52e9193aa4945598f7da31d202cfc445f2b5b63009f5f09e260a732b02e3ac64
 SHA512:
-  metadata.gz: cbf5bd49d6c3b912ff8e3b8061cae4e2b1eaea00f913c8f217058168e7008f3c4daaeef0888ca22bce22d318742db1890c8524293e20734b4dea506fc3eeae10
-  data.tar.gz: 744519a43e3f1eb98527cbcb5495700b16a6ea94de95732baf8027debc14df7e5fa0394f804a9360383eb9168d3975794b46c4a0a6c45d1b769fd0c94e1700b5
+  metadata.gz: b0f02df991559f21667288ebf690695909d65766cb2c9dd809d18d62a34e722d35d898e227ef38cf12d5acf96d271b7c0a078b1aa8ce47b93645fdd27b36d043
+  data.tar.gz: 5f60948e47cebdc9ff2de6a594aa68155c39ee262fd0662afbe293b672ce811c74a5182f8793be7d3860a8361560213108f25fd00d8a1891cd72a353d3103b25

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.0.10] - 2024-02-27
+### Changed
+- Minor documentation updates;
+
+## [0.0.9] - 2024-02-27
+### Changed
+- The lock acquier identifier (`acq_id`) now includes the fiber id, the ractor id and an unique per-process
+  10 byte string. It is added in order to prevent collisions between different processes/pods
+  that will have the same procjet id / thread id identifiers (cuz it is an object_id integers) that can lead
+  to the same position with the same `acq_id` for different processes/pods in the lock request queue.
+
 ## [0.0.8] - 2024-02-27
 ### Added
 - `RedisQueuedLock::Client#locked?`

data/README.md

@@ -60,7 +60,7 @@ require 'redis_queued_locks'
 require 'redis_queued_locks'
 
 # Step 1: initialize RedisClient instance
-redis_clinet = RedisClient.config.new_pool # NOTE: provide your ounw RedisClient instance
+redis_client = RedisClient.config.new_pool # NOTE: provide your own RedisClient instance
 
 # Step 2: initialize RedisQueuedLock::Client instance
 rq_lock_client = RedisQueuedLocks::Client.new(redis_client) do |config|
@@ -119,6 +119,14 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - payload: <hash> requried;
   # - disabled by default via VoidNotifier;
   config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
+
+  # (default: -> { RedisQueuedLocks::Resource.calc_uniq_identity })
+  # - uniqude idenfitier that is uniq per process/pod;
+  # - prevents potential lock-acquirement collisions bettween different process/pods
+  #   that have identical process_id/thread_id/fiber_id/ractor_id (identivcal acquier ids);
+  # - it is calculated once per `RedisQueudLocks::Client` instance;
+  # - expects the proc object;
+  config.uniq_identifier = -> { RedisQueuedLocks::Resource.calc_uniq_identity }
 end
 ```
 
@@ -142,8 +150,6 @@ end
 ```ruby
 def lock(
   lock_name,
-  process_id: RedisQueuedLocks::Resource.get_process_id,
-  thread_id: RedisQueuedLocks::Resource.get_thread_id,
   ttl: config[:default_lock_ttl],
   queue_ttl: config[:default_queue_ttl],
   timeout: config[:try_to_lock_timeout],
@@ -151,16 +157,13 @@ def lock(
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
   raise_errors: false,
+  identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   &block
 )
 ```
 
 - `lock_name` - `[String]`
   - Lock name to be obtained.
-- `process_id` - `[Integer,String]`
-  - The process that want to acquire the lock.
-- `thread_id` - `[Integer,String]`
-  - The process's thread that want to acquire the lock.
 - `ttl` [Integer]
   - Lock's time to live (in milliseconds).
 - `queue_ttl` - `[Integer]`
@@ -177,6 +180,12 @@ def lock(
   - See RedisQueuedLocks::Instrument::ActiveSupport for example.
 - `raise_errors` - `[Boolean]`
   - Raise errors on library-related limits such as timeout or retry count limit.
+- `identity` - `[String]`
+  - An unique string that is unique per `RedisQueuedLock::Client` instance. Resolves the
+    collisions between the same process_id/thread_id/fiber_id/ractor_id identifiers on different
+    pods or/and nodes of your application;
+  - It is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`
+    ivar (accessed via `uniq_dentity` accessor method);
 - `block` - `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
@@ -190,7 +199,7 @@ Return value:
     ok: true,
     result: {
       lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
-      acq_id: String, # acquier identifier ("your_process_id/your_thread_id")
+      acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
       ts: Integer, # time (epoch) when lock was obtained (integer)
       ttl: Integer # lock's time to live in milliseconds (integer)
     }
@@ -214,14 +223,13 @@ Return value:
 ```ruby
 def lock!(
   lock_name,
-  process_id: RedisQueuedLocks::Resource.get_process_id,
-  thread_id: RedisQueuedLocks::Resource.get_thread_id,
   ttl: config[:default_lock_ttl],
   queue_ttl: config[:default_queue_ttl],
   timeout: config[:default_timeout],
   retry_count: config[:retry_count],
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
+  identity: uniq_identity,
   &block
 )
 ```
@@ -236,7 +244,7 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 - returns `nil` if lock does not exist;
 - lock data (`Hash<Symbol,String|Integer>`):
   - `lock_key` - `string` - lock key in redis;
-  - `acq_id` - `string` - acquier identifier (process_id/thread_id by default);
+  - `acq_id` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity);
   - `ts` - `integer`/`epoch` - the time lock was obtained;
   - `init_ttl` - `integer` - (milliseconds) initial lock key ttl;
   - `rem_ttl` - `integer` - (milliseconds) remaining lock key ttl;
@@ -247,7 +255,7 @@ rql.lock_info("your_lock_name")
 # =>
 {
   lock_key: "rql:lock:your_lock_name",
-  acq_id: "rql:acq:123/456",
+  acq_id: "rql:acq:123/456/567/678/374dd74324",
   ts: 123456789,
   ini_ttl: 123456789,
   rem_ttl: 123456789
@@ -267,7 +275,7 @@ rql.lock_info("your_lock_name")
 - lock queue data (`Hash<Symbol,String|Array<Hash<Symbol,String|Numeric>>`):
   - `lock_queue` - `string` - lock queue key in redis;
   - `queue` - `array` - an array of lock requests (array of hashes):
-    - `acq_id` - `string` - acquier identifier (process_id/thread_id by default);
+    - `acq_id` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity by default);
     - `score` - `float`/`epoch` - time when the lock request was made (epoch);
 
 ```ruby
@@ -277,9 +285,9 @@ rql.queue_info("your_lock_name")
 {
   lock_queue: "rql:lock_queue:your_lock_name",
   queue: [
-    { acq_id: "rql:acq:123/456", score: 1},
-    { acq_id: "rql:acq:123/567", score: 2},
-    { acq_id: "rql:acq:555/329", score: 3},
+    { acq_id: "rql:acq:123/456/567/678/fa76df9cc2", score: 1},
+    { acq_id: "rql:acq:123/567/456/679/c7bfcaf4f9", score: 2},
+    { acq_id: "rql:acq:555/329/523/127/7329553b11", score: 3},
     # ...etc
   ]
 }
@@ -422,7 +430,7 @@ Detalized event semantics and payload structure:
   - payload:
     - `rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
     - `at` - `integer`/`epoch` - the time when the operation has ended;
-    - `rel_keys` - `integer` - released redis keys count (`released queu keys` + `released lock keys`);
+    - `rel_keys` - `integer` - released redis keys count (`released queue keys` + `released lock keys`);
 
 ---
 
@@ -431,6 +439,7 @@ Detalized event semantics and payload structure:
 - **Major**
   - Semantic Error objects for unexpected Redis errors;
   - `100%` test coverage;
+  - sidecar `Ractor` object and `in progress queue` in RedisDB that will extend an acquired lock for long-running blocks of code (that invoked "under" the lock);
 - **Minor**
   - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
   - better code stylization and interesting refactorings;

data/lib/redis_queued_locks/acquier.rb

@@ -34,9 +34,13 @@ module RedisQueuedLocks::Acquier
     # @param lock_name [String]
     #   Lock name to be acquier.
     # @option process_id [Integer,String]
-    #   The process that want to acquire the lock.
+    #   The process that want to acquire a lock.
     # @option thread_id [Integer,String]
-    #   The process's thread that want to acquire the lock.
+    #   The process's thread that want to acquire a lock.
+    # @option fiber_id [Integer,String]
+    #   A current fiber that want to acquire a lock.
+    # @option ractor_id [Integer,String]
+    #   The current ractor that want to acquire a lock.
     # @option ttl [Integer,NilClass]
     #   Lock's time to live (in milliseconds). Nil means "without timeout".
     # @option queue_ttl [Integer]
@@ -53,6 +57,10 @@ module RedisQueuedLocks::Acquier
     #   Raise errors on exceptional cases.
     # @option instrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @option identity [String]
+    #   Unique acquire identifier that is also should be unique between processes and pods
+    #   on different machines. By default the uniq identity string is
+    #   represented as 10 bytes hexstr.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [Hash<Symbol,Any>]
@@ -66,6 +74,8 @@ module RedisQueuedLocks::Acquier
       lock_name,
       process_id:,
       thread_id:,
+      fiber_id:,
+      ractor_id:,
       ttl:,
       queue_ttl:,
       timeout:,
@@ -74,10 +84,17 @@ module RedisQueuedLocks::Acquier
       retry_jitter:,
       raise_errors:,
       instrumenter:,
+      identity:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
-      acquier_id = RedisQueuedLocks::Resource.acquier_identifier(process_id, thread_id)
+      acquier_id = RedisQueuedLocks::Resource.acquier_identifier(
+        process_id,
+        thread_id,
+        fiber_id,
+        ractor_id,
+        identity
+      )
       lock_ttl = ttl + REDIS_EXPIRATION_DEVIATION
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
@@ -386,6 +403,17 @@ module RedisQueuedLocks::Acquier
       end
     end
 
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @param milliseconds [Integer]
+    # @return [?]
+    #
+    # @api private
+    # @since 0.1.0
+    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+
+    end
+
     private
 
     # @param timeout [NilClass,Integer]

data/lib/redis_queued_locks/client.rb

@@ -17,6 +17,7 @@ class RedisQueuedLocks::Client
     setting :default_queue_ttl, 15 # NOTE: seconds
     setting :lock_release_batch_size, 100
     setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
+    setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
 
     # TODO: setting :logger, Logger.new(IO::NULL)
     # TODO: setting :debug, true/false
@@ -30,6 +31,7 @@ class RedisQueuedLocks::Client
     validate('default_queue_ttl', :integer)
     validate('lock_release_batch_size', :integer)
     validate('instrumenter') { |val| RedisQueuedLocks::Instrument.valid_interface?(val) }
+    validate('uniq_identifier', :proc)
   end
 
   # @return [RedisClient]
@@ -38,6 +40,12 @@ class RedisQueuedLocks::Client
   # @since 0.1.0
   attr_reader :redis_client
 
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_accessor :uniq_identity
+
   # @param redis_client [RedisClient]
   #   Redis connection manager, which will be used for the lock acquierment and distribution.
   #   It should be an instance of RedisClient.
@@ -49,15 +57,12 @@ class RedisQueuedLocks::Client
   # @since 0.1.0
   def initialize(redis_client, &configs)
     configure(&configs)
+    @uniq_identity = config[:uniq_identifier].call
     @redis_client = redis_client
   end
 
   # @param lock_name [String]
   #   Lock name to be obtained.
-  # @option process_id [Integer,String]
-  #   The process that want to acquire the lock.
-  # @option thread_id [Integer,String]
-  #   The process's thread that want to acquire the lock.
   # @option ttl [Integer]
   #   Lock's time to live (in milliseconds).
   # @option queue_ttl [Integer]
@@ -74,17 +79,19 @@ class RedisQueuedLocks::Client
   #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
   # @option raise_errors [Boolean]
   #   Raise errors on library-related limits such as timeout or failed lock obtain.
+  # @option identity [String]
+  #   Unique acquire identifier that is also should be unique between processes and pods
+  #   on different machines. By default the uniq identity string is
+  #   represented as 10 bytes hexstr.
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
-  # @return [Hash<Symbol,Any>]
+  # @return [Hash<Symbol,Any>,yield]
   #   Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
   def lock(
     lock_name,
-    process_id: RedisQueuedLocks::Resource.get_process_id,
-    thread_id: RedisQueuedLocks::Resource.get_thread_id,
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
@@ -92,13 +99,16 @@ class RedisQueuedLocks::Client
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
     raise_errors: false,
+    identity: uniq_identity,
     &block
   )
     RedisQueuedLocks::Acquier.acquire_lock!(
       redis_client,
       lock_name,
-      process_id:,
-      thread_id:,
+      process_id: RedisQueuedLocks::Resource.get_process_id,
+      thread_id: RedisQueuedLocks::Resource.get_thread_id,
+      fiber_id: RedisQueuedLocks::Resource.get_fiber_id,
+      ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
       ttl:,
       queue_ttl:,
       timeout:,
@@ -107,6 +117,7 @@ class RedisQueuedLocks::Client
       retry_jitter:,
       raise_errors:,
       instrumenter: config[:instrumenter],
+      identity:,
       &block
     )
   end
@@ -117,20 +128,17 @@ class RedisQueuedLocks::Client
   # @since 0.1.0
   def lock!(
     lock_name,
-    process_id: RedisQueuedLocks::Resource.get_process_id,
-    thread_id: RedisQueuedLocks::Resource.get_thread_id,
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:default_timeout],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
+    identity: uniq_identity,
     &block
   )
     lock(
       lock_name,
-      process_id:,
-      thread_id:,
       ttl:,
       queue_ttl:,
       timeout:,
@@ -138,6 +146,7 @@ class RedisQueuedLocks::Client
       retry_delay:,
       retry_jitter:,
       raise_errors: true,
+      identity:,
       &block
     )
   end
@@ -148,11 +157,7 @@ class RedisQueuedLocks::Client
   # @api public
   # @since 0.1.0
   def unlock(lock_name)
-    RedisQueuedLocks::Acquier.release_lock!(
-      redis_client,
-      lock_name,
-      config[:instrumenter]
-    )
+    RedisQueuedLocks::Acquier.release_lock!(redis_client, lock_name, config[:instrumenter])
   end
 
   # @param lock_name [String]
@@ -191,17 +196,23 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier.queue_info(redis_client, lock_name)
   end
 
+  # @param lock_name [String]
+  # @param milliseconds [Integer] How many milliseconds should be added.
+  # @return [?]
+  #
+  # @api public
+  # @since 0.1.0
+  def extend_lock_ttl(lock_name, milliseconds)
+    RedisQueuedLocks::Acquier.extend_lock_ttl(redis_client, lock_name)
+  end
+
   # @option batch_size [Integer]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
   def clear_locks(batch_size: config[:lock_release_batch_size])
-    RedisQueuedLocks::Acquier.release_all_locks!(
-      redis_client,
-      batch_size,
-      config[:instrumenter]
-    )
+    RedisQueuedLocks::Acquier.release_all_locks!(redis_client, batch_size, config[:instrumenter])
   end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/resource.rb

@@ -16,14 +16,29 @@ module RedisQueuedLocks::Resource
   LOCK_QUEUE_PATTERN = 'rql:lock_queue:*'
 
   class << self
+    # Returns 10-byte unique identifier. It is used for uniquely
+    # identify current process between different nodes/pods of your application
+    # during the lock obtaining and self-identifying in the lock queue.
+    #
+    # @return [String]
+    #
+    # @api private
+    # @since 0.1.0
+    def calc_uniq_identity
+      SecureRandom.hex(5)
+    end
+
     # @param process_id [Integer,String]
     # @param thread_id [Integer,String]
+    # @param fiber_id [Integer,String]
+    # @param ractor_id [Integer,String]
+    # @param identity [String]
     # @return [String]
     #
     # @api private
     # @since 0.1.0
-    def acquier_identifier(process_id = get_process_id, thread_id = get_thread_id)
-      "rql:acq:#{process_id}/#{thread_id}"
+    def acquier_identifier(process_id, thread_id, fiber_id, ractor_id, identity)
+      "rql:acq:#{process_id}/#{thread_id}/#{fiber_id}/#{ractor_id}/#{identity}"
     end
 
     # @param lock_name [String]
@@ -79,6 +94,22 @@ module RedisQueuedLocks::Resource
       ::Thread.current.object_id
     end
 
+    # @return [Integer]
+    #
+    # @api private
+    # @since 0.1.0
+    def get_fiber_id
+      ::Fiber.current.object_id
+    end
+
+    # @return [Integer]
+    #
+    # @api private
+    # @since 0.1.0
+    def get_ractor_id
+      ::Ractor.current.object_id
+    end
+
     # @return [Integer]
     #
     # @api private

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 0.0.8
-  VERSION = '0.0.8'
+  # @version 0.0.10
+  VERSION = '0.0.10'
 end

data/lib/redis_queued_locks.rb

@@ -3,6 +3,7 @@
 require 'redis-client'
 require 'qonfig'
 require 'timeout'
+require 'securerandom'
 
 # @api public
 # @since 0.1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.10
 platform: ruby
 authors:
 - Rustam Ibragimov