redis_queued_locks 0.0.29 → 0.0.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3137184f5a89b895fe347d8080957e08a57974e91d5a68189d0eb157afd7c3eb
-  data.tar.gz: 7b059f5de5cde2af1634eed3aeae540afd7edfc5ba564781789649098e53e0a1
+  metadata.gz: d33fd5af73686a34765eb95c54fe9dc28b107a01768e41b2a28150dffdc72a60
+  data.tar.gz: 0ac04f452fbd00b01df535a48dd724e360ed66f42459e33fbf989427531c6b6a
 SHA512:
-  metadata.gz: 4821b6c0fc142d90fae314aa11c92069be9223cc4a61be077ff6e19278fae97f920d31b590c5688f3614159a2f5c9d9d1792d8a6aee50f51d7b24f83ea1a9298
-  data.tar.gz: 80a0de485f263459c52d230cc0e604d0c742db235a6a9b57053cc84001e9e146cfc35b9c31aff5e1ef5a2796692559f95fe94db39350720277fb219ef95a2685
+  metadata.gz: 419d36772547c3a7010353d6589b62c442cd7e2575a1c96fcf8ebcee9be83c002a44de7a5dc6de8faa6e32c76f044bf5eaf659ddaf156e8eb3093587dab54e90
+  data.tar.gz: 28ba2de724d7d7540d967e9ade24ca6d65126af526224ae90f418c04e58618ff1aa856911d9eef363b004272fda73a0ce5ddf83a52460e4d78f09dabdd9fba3f

data/CHANGELOG.md

@@ -1,8 +1,35 @@
 ## [Unreleased]
 
+## [0.0.32] - 2024-03-26
+### Added
+- Support for custom metadata that merged to the lock data. This data also returned from `RedisQueudLocks::Client#lock_info` method;
+  - Custom metadata shou;d be represented as a `key => value` `Hash` data (or `NilClass` instead);
+  - Custom metadata values is returned as raw data from Redis (commonly as strings);
+  - Custom metadata can not contain reserved lock data keys;
+- Reduced some memory consuption;
+### Changed
+- `RedisQueuedLocks::Client#lock_info` - has keys is changed from `Symbol` type to `String` type;
+- `RedisQueuedLocks::Client#queue_info` - hash keys is changed from `Symbol` type to `String` type;
+
+## [0.0.31] - 2024-03-25
+### Changed
+- `:metadata` renamed to `:instrument` in order to reflect it's domain area;
+- `:metadata` is renamed to `:meta` and reserved for the future updates;
+
+## [0.0.30] - 2024-03-23
+### Fixed
+- Re-enqueue problem: fixed a problem when the expired lock requests were infinitly re-added to the lock queue
+  and immediately removed from the lock queue rather than being re-positioned. It happens when the lock request
+  ttl reached the queue ttl, and the new request now had the dead score forever (fix: it's score now will be correctly
+  recalculated from the current time at the dead score time moment);
+### Added
+- Logging: more detailed logs to the `RedisQueuedLocks::Acquier::AcquierLock` logic and it's sub-modules:
+  - added new logs;
+  - added `queue_ttl` to each log;
+
 ## [0.0.29] - 2024-03-23
 ### Added
-- Logging: more detailed logs to `RedisQueuedLocks::Acquier::AcquireLock::TryToLock`;
+- Logging: added more detailed logs to `RedisQueuedLocks::Acquier::AcquireLock::TryToLock`;
 
 ## [0.0.28] - 2024-03-21
 ### Added

data/README.md

@@ -2,7 +2,9 @@
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
-Each lock request is put into the request queue and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
+Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttls, queue ttls, fast failing, etc), logging and instrumentation.
+
+Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees the request queue will never be stacked.
 
 ---
 
@@ -14,7 +16,7 @@ Each lock request is put into the request queue and processed in order of their
 - [Configuration](#configuration)
 - [Usage](#usage)
   - [lock](#lock---obtain-a-lock)
-  - [lock!](#lock---exeptional-lock-obtaining)
+  - [lock!](#lock---exceptional-lock-obtaining)
   - [lock_info](#lock_info)
   - [queue_info](#queue_info)
   - [locked?](#locked)
@@ -36,7 +38,7 @@ Each lock request is put into the request queue and processed in order of their
 
 ### Algorithm
 
-> Each lock request is put into the request queue and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
+> Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
 
 **Soon**: detailed explanation.
 
@@ -194,7 +196,8 @@ def lock(
   raise_errors: false,
   fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
-  metadata: nil,
+  meta: nil,
+  instrument: nil,
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   &block
@@ -232,8 +235,11 @@ def lock(
     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);
-- `metadata` - `[NilClass,Any]`
-  - A custom metadata wich will be passed to the instrumenter's payload with `:meta` key;
+- `meta` - `[NilClass,Hash<String|Symbol,Any>]`
+  - A custom metadata wich will be passed to the lock data in addition to the existing data;
+  - Custom metadata can not contain reserved lock data keys (such as `lock_key`, `acq_id`, `ts`, `ini_ttl`, `rem_ttl`);
+- `instrument` - `[NilClass,Any]`
+  - Custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
 - `logger` - `[::Logger,#debug]`
   - Logger object used from the configuration layer (see config[:logger]);
   - See `RedisQueuedLocks::Logging::VoidLogger` for example;
@@ -293,7 +299,8 @@ def lock!(
   retry_jitter: config[:retry_jitter],
   identity: uniq_identity,
   fail_fast: false,
-  metadata: nil,
+  meta: nil,
+  instrument: nil,
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   &block
@@ -309,22 +316,42 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 - get the lock information;
 - 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/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;
+  - `"lock_key"` - `string` - lock key in redis;
+  - `"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;
+  - custom metadata keys - `String` - custom metadata passed to the `lock`/`lock!`
+    methods via `meta:` keyword argument (see [lock]((#lock---obtain-a-lock)) method documentation);
+
+```ruby
+# without custom metadata
+rql.lock_info("your_lock_name")
+
+# =>
+{
+  "lock_key" => "rql:lock:your_lock_name",
+  "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "ts" => 123456789,
+  "ini_ttl" => 123456789,
+  "rem_ttl" => 123456789
+}
+```
 
 ```ruby
+# with custom metadata
+rql.lock("your_lock_name", meta: { "kek" => "pek", "bum" => 123 })
 rql.lock_info("your_lock_name")
 
 # =>
 {
-  lock_key: "rql:lock:your_lock_name",
-  acq_id: "rql:acq:123/456/567/678/374dd74324",
-  ts: 123456789,
-  ini_ttl: 123456789,
-  rem_ttl: 123456789
+  "lock_key" => "rql:lock:your_lock_name",
+  "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "ts" => 123456789,
+  "ini_ttl" => 123456789,
+  "rem_ttl" => 123456789,
+  "kek" => "pek",
+  "bum" => "123" # NOTE: returned as a raw string directly from Redis
 }
 ```
 
@@ -339,10 +366,10 @@ rql.lock_info("your_lock_name")
   - represents the acquier identifier and their score as an array of hashes;
 - returns `nil` if lock queue does not exist;
 - 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/fiber_id/ractor_id/identity by default);
-    - `score` - `float`/`epoch` - time when the lock request was made (epoch);
+  - `"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/fiber_id/ractor_id/identity by default);
+    - `"score"` - `float`/`epoch` - time when the lock request was made (epoch);
 
 ```
 | Returns an information about the required lock queue by the lock name. The result
@@ -357,11 +384,11 @@ rql.queue_info("your_lock_name")
 
 # =>
 {
-  lock_queue: "rql:lock_queue:your_lock_name",
-  queue: [
-    { 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},
+  "lock_queue" => "rql:lock_queue:your_lock_name",
+  "queue" => [
+    { "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
   ]
 }
@@ -604,7 +631,8 @@ Detalized event semantics and payload structure:
 - `100%` test coverage;
 - per-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
   the acquired lock for long-running blocks of code (that invoked "under" the lock
-  whose ttl may expire before the block execution completes);
+  whose ttl may expire before the block execution completes). It only makes sens for non-`timed` locks
+  (for those locks where otaned with `timed: false` option);
 - an ability to add custom metadata to the lock and an ability to read this data;
 - lock prioritization;
 - support for LIFO strategy;
@@ -613,6 +641,7 @@ Detalized event semantics and payload structure:
 - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
 - better code stylization and interesting refactorings;
 - dead queue cleanup;
+- statistics with UI;
 - support for `Dragonfly` DB backend;
 - support for `Garnet` DB backend;
 

data/lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb

@@ -17,6 +17,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param ttl [Integer]
   # @param queue_ttl [Integer]
   # @param fail_fast [Boolean]
+  # @param meta [NilClass,Hash<String|Symbol,Any>]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
@@ -32,7 +33,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     acquier_position,
     ttl,
     queue_ttl,
-    fail_fast
+    fail_fast,
+    meta
   )
     # Step X: intermediate invocation results
     inter_result = nil
@@ -43,23 +45,26 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
         logger.debug(
           "[redis_queued_locks.try_lock.start] " \
           "lock_key => '#{lock_key}' " \
-          "acq_id => '#{acquier_id}'"
+          "queue_ttl => #{queue_ttl} " \
+          "acq_id => '#{acquier_id}' "
         )
       end
     end
 
-    # Step 0: watch the lock key changes (and discard acquirement if lock is already acquired)
+    # Step X: start to work with lock acquiring
     result = redis.with do |rconn|
       if log_lock_try
         run_non_critical do
           logger.debug(
             "[redis_queued_locks.try_lock.rconn_fetched] " \
             "lock_key => '#{lock_key}' " \
+            "queue_ttl => #{queue_ttl} " \
             "acq_id => '#{acquier_id}'"
           )
         end
       end
 
+      # Step 0: watch the lock key changes (and discard acquirement if lock is already acquired)
       rconn.multi(watch: [lock_key]) do |transact|
         # Fast-Step X0: fail-fast check
         if fail_fast && rconn.call('HGET', lock_key, 'acq_id')
@@ -74,6 +79,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               logger.debug(
                 "[redis_queued_locks.try_lock.acq_added_to_queue] " \
                 "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
               )
             end
@@ -96,6 +102,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               logger.debug(
                 "[redis_queued_locks.try_lock.remove_expired_acqs] " \
                 "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
               )
             end
@@ -113,6 +120,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               logger.debug(
                 "[redis_queued_locks.try_lock.get_first_from_queue] " \
                 "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}' " \
                 "first_acq_id_in_queue => '#{waiting_acquier}'"
               )
@@ -124,8 +132,28 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
           )
 
+          # Step PRE-4.x: check if the request time limit is reached
+          #   (when the current try self-removes itself from queue (queue ttl has come))
+          if waiting_acquier == nil
+            if log_lock_try
+              run_non_critical do
+                logger.debug(
+                  "[redis_queued_locks.try_lock.exit__queue_ttl_reached] " \
+                  "lock_key => '#{lock_key}' " \
+                  "queue_ttl => #{queue_ttl} " \
+                  "acq_id => '#{acquier_id}'"
+                )
+              end
+            end
+
+            RedisQueuedLocks.debug(
+              "Step PRE-ROLLBACK №0: достигли лимита времени эквайра лока (queue ttl). выходим. " \
+              "[Наша позиция: #{acquier_id}. queue_ttl: #{queue_ttl}]"
+            )
+
+            inter_result = :dead_score_reached
           # Step 4: check the actual acquier: is it ours? are we aready to lock?
-          unless waiting_acquier == acquier_id
+          elsif waiting_acquier != acquier_id
             # Step ROLLBACK 1.1: our time hasn't come yet. retry!
 
             if log_lock_try
@@ -133,6 +161,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                 logger.debug(
                   "[redis_queued_locks.try_lock.exit__no_first] " \
                   "lock_key => '#{lock_key}' " \
+                  "queue_ttl => #{queue_ttl} " \
                   "acq_id => '#{acquier_id}' " \
                   "first_acq_id_in_queue => '#{waiting_acquier}'"
                 )
@@ -167,6 +196,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                   logger.debug(
                     "[redis_queued_locks.try_lock.exit__still_obtained] " \
                     "lock_key => '#{lock_key}' " \
+                    "queue_ttl => #{queue_ttl} " \
                     "acq_id => '#{acquier_id}' " \
                     "first_acq_id_in_queue => '#{waiting_acquier}' " \
                     "locked_by_acq_id => '#{locked_by_acquier}'"
@@ -202,7 +232,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                 lock_key,
                 'acq_id', acquier_id,
                 'ts', (timestamp = Time.now.to_f),
-                'ini_ttl', ttl
+                'ini_ttl', ttl,
+                *(meta.to_a if meta != nil)
               )
 
               # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
@@ -213,6 +244,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                   logger.debug(
                     "[redis_queued_locks.try_lock.run__free_to_acquire] " \
                     "lock_key => '#{lock_key}' " \
+                    "queue_ttl => #{queue_ttl} " \
                     "acq_id => '#{acquier_id}'"
                   )
                 end
@@ -229,6 +261,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     when fail_fast && inter_result == :fail_fast_no_try
       # Step 7.a: lock is still acquired and we should exit from the logic as soon as possible
       RedisQueuedLocks::Data[ok: false, result: inter_result]
+    when inter_result == :dead_score_reached
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     when inter_result == :lock_is_still_acquired || inter_result == :acquier_is_not_first_in_queue
       # Step 7.b: lock is still acquired by another process => failed to acquire
       RedisQueuedLocks::Data[ok: false, result: inter_result]

data/lib/redis_queued_locks/acquier/acquire_lock/with_acq_timeout.rb

@@ -21,9 +21,11 @@ module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
     on_timeout.call unless on_timeout == nil
 
     if raise_errors
-      raise(RedisQueuedLocks::LockAcquiermentTimeoutError, <<~ERROR_MESSAGE.strip)
-        Failed to acquire the lock "#{lock_key}" for the given timeout (#{timeout} seconds).
-      ERROR_MESSAGE
+      raise(
+        RedisQueuedLocks::LockAcquiermentTimeoutError,
+        "Failed to acquire the lock \"#{lock_key}\" " \
+        "for the given timeout (#{timeout} seconds)."
+      )
     end
   end
 end

data/lib/redis_queued_locks/acquier/acquire_lock/yield_with_expire.rb

@@ -13,12 +13,23 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   # @param timed [Boolean] Should the lock be wrapped by Tiemlout with with lock's ttl
   # @param ttl_shift [Float] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
   # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
+  # @param queue_ttl [Integer] Lock request lifetime.
   # @param block [Block] Custom logic that should be invoked unter the obtained lock.
   # @return [Any,NilClass] nil is returned no block parametr is provided.
   #
   # @api private
   # @since 0.1.0
-  def yield_with_expire(redis, logger, lock_key, acquier_id, timed, ttl_shift, ttl, &block)
+  def yield_with_expire(
+    redis,
+    logger,
+    lock_key,
+    acquier_id,
+    timed,
+    ttl_shift,
+    ttl,
+    queue_ttl,
+    &block
+  )
     if block_given?
       if timed && ttl != nil
         timeout = ((ttl - ttl_shift) / 1000.0).yield_self { |time| (time < 0) ? 0.0 : time }
@@ -32,6 +43,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
       logger.debug(
         "[redis_queued_locks.expire_lock] " \
         "lock_key => '#{lock_key}' " \
+        "queue_ttl => #{queue_ttl} " \
         "acq_id => '#{acquier_id}'"
       )
     end
@@ -51,8 +63,10 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   def yield_with_timeout(timeout, lock_key, lock_ttl, &block)
     ::Timeout.timeout(timeout, &block)
   rescue ::Timeout::Error
-    raise(RedisQueuedLocks::TimedLockTimeoutError, <<~ERROR_MESSAGE)
-      Passed <timed> block of code exceeded the lock TTL (lock: "#{lock_key}", ttl: #{lock_ttl})
-    ERROR_MESSAGE
+    raise(
+      RedisQueuedLocks::TimedLockTimeoutError,
+      "Passed <timed> block of code exceeded " \
+      "the lock TTL (lock: \"#{lock_key}\", ttl: #{lock_ttl})"
+    )
   end
 end

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -67,8 +67,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
     # @option fail_fast [Boolean]
     #   Should the required lock to be checked before the try and exit immidetly if lock is
     #   already obtained.
-    # @option metadata [NilClass,Any]
-    #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
+    # @option meta [NilClass,Hash<String|Symbol,Any>]
+    #   - A custom metadata wich will be passed to the lock data in addition to the existing data;
+    #   - Metadata can not contain reserved lock data keys;
     # @option logger [::Logger,#debug]
     #   - Logger object used from the configuration layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
@@ -76,6 +77,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   - should be logged the each try of lock acquiring (a lot of logs can be generated depending
     #     on your retry configurations);
     #   - see `config[:log_lock_try]`;
+    # @option instrument [NilClass,Any]
+    #    - Custom instrumentation data wich will be passed to the instrumenter's payload
+    #      with :instrument key;
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -102,11 +106,38 @@ module RedisQueuedLocks::Acquier::AcquireLock
       instrumenter:,
       identity:,
       fail_fast:,
-      metadata:,
+      meta:,
+      instrument:,
       logger:,
       log_lock_try:,
       &block
     )
+      # Step 0: Prevent argument type incompatabilities
+      # Step 0.1: prevent :meta incompatabiltiies (type)
+      case meta # NOTE: do not ask why case/when is used here
+      when Hash, NilClass then nil
+      else
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:meta` argument should be a type of NilClass or Hash, got #{meta.class}."
+        )
+      end
+
+      # Step 0.2: prevent :meta incompatabiltiies (structure)
+      if meta == ::Hash && (meta.keys.any? do |key|
+        key == 'acq_id' ||
+        key == 'ts' ||
+        key == 'ini_ttl' ||
+        key == 'lock_key' ||
+        key == 'rem_ttl'
+      end)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          '`:meta` keys can not overlap reserved lock data keys' \
+          '"acq_id", "ts", "ini_ttl", "lock_key", "rem_ttl"'
+        )
+      end
+
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
       acquier_id = RedisQueuedLocks::Resource.acquier_identifier(
         process_id,
@@ -140,6 +171,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
         logger.debug(
           "[redis_queued_locks.start_lock_obtaining] " \
           "lock_key => '#{lock_key}' " \
+          "queue_ttl => #{queue_ttl} " \
           "acq_id => '#{acquier_id}'"
         )
       end
@@ -150,6 +182,30 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
         # Step 2.1: caclically try to obtain the lock
         while acq_process[:should_try]
+          run_non_critical do
+            logger.debug(
+              "[redis_queued_locks.start_try_to_lock_cycle] " \
+              "lock_key => '#{lock_key}' " \
+              "queue_ttl => #{queue_ttl} " \
+              "acq_id => '{#{acquier_id}'"
+            )
+          end
+
+          # Step 2.X: check the actual score: is it in queue ttl limit or not?
+          if RedisQueuedLocks::Resource.dead_score_reached?(acquier_position, queue_ttl)
+            # Step 2.X.X: dead score reached => re-queue the lock request with the new score;
+            acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
+
+            run_non_critical do
+              logger.debug(
+                "[redis_queued_locks.dead_score_reached__reset_acquier_position] " \
+                "lock_key => '#{lock_key} " \
+                "queue_ttl => #{queue_ttl} " \
+                "acq_id => '#{acquier_id}'"
+              )
+            end
+          end
+
           try_to_lock(
             redis,
             logger,
@@ -160,7 +216,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
             acquier_position,
             lock_ttl,
             queue_ttl,
-            fail_fast
+            fail_fast,
+            meta
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
@@ -176,6 +233,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               logger.debug(
                 "[redis_queued_locks.lock_obtained] " \
                 "lock_key => '#{result[:lock_key]}' " \
+                "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}' " \
                 "acq_time => #{acq_time} (ms)"
               )
@@ -189,7 +247,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 acq_id: result[:acq_id],
                 ts: result[:ts],
                 acq_time: acq_time,
-                meta: metadata
+                instrument:
               })
             end
 
@@ -207,9 +265,10 @@ module RedisQueuedLocks::Acquier::AcquireLock
           elsif fail_fast && acq_process[:result] == :fail_fast_no_try
             acq_process[:should_try] = false
             if raise_errors
-              raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
-                Lock "#{lock_key}" is already obtained.
-              ERROR_MESSAGE
+              raise(
+                RedisQueuedLocks::LockAlreadyObtainedError,
+                "Lock \"#{lock_key}\" is already obtained."
+              )
             end
           else
             # Step 2.1.b: failed acquirement => retry
@@ -229,18 +288,20 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
               # NOTE: check and raise an error
               if fail_fast && raise_errors
-                raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
-                  Lock "#{lock_key}" is already obtained.
-                ERROR_MESSAGE
+                raise(
+                  RedisQueuedLocks::LockAlreadyObtainedError,
+                  "Lock \"#{lock_key}\" is already obtained."
+                )
               elsif raise_errors
-                raise(RedisQueuedLocks::LockAcquiermentRetryLimitError, <<~ERROR_MESSAGE.strip)
-                  Failed to acquire the lock "#{lock_key}"
-                  for the given retry_count limit (#{retry_count} times).
-                ERROR_MESSAGE
+                raise(
+                  RedisQueuedLocks::LockAcquiermentRetryLimitError,
+                  "Failed to acquire the lock \"#{lock_key}\" " \
+                  "for the given retry_count limit (#{retry_count} times)."
+                )
               end
             else
               # NOTE:
-              #   delay the exceution in order to prevent chaotic attempts
+              #   delay the exceution in order to prevent chaotic lock-acquire attempts
               #   and to allow other processes and threads to obtain the lock too.
               delay_execution(retry_delay, retry_jitter)
             end
@@ -255,7 +316,17 @@ module RedisQueuedLocks::Acquier::AcquireLock
           begin
             yield_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             ttl_shift = ((yield_time - acq_process[:acq_end_time]) * 1000).ceil(2)
-            yield_with_expire(redis, logger, lock_key, acquier_id, timed, ttl_shift, ttl, &block)
+            yield_with_expire(
+              redis,
+              logger,
+              lock_key,
+              acquier_id,
+              timed,
+              ttl_shift,
+              ttl,
+              queue_ttl,
+              &block
+            )
           ensure
             acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             acq_process[:hold_time] = (
@@ -271,7 +342,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 ts: acq_process[:lock_info][:ts],
                 lock_key: acq_process[:lock_info][:lock_key],
                 acq_time: acq_process[:acq_time],
-                meta: metadata
+                instrument:
               })
             end
           end

data/lib/redis_queued_locks/acquier/lock_info.rb

@@ -6,14 +6,14 @@ module RedisQueuedLocks::Acquier::LockInfo
   class << self
     # @param redis_client [RedisClient]
     # @param lock_name [String]
-    # @return [Hash<Symbol,String|Numeric>,NilClass]
+    # @return [Hash<String,String|Numeric>,NilClass]
     #   - `nil` is returned when lock key does not exist or expired;
     #   - result format: {
-    #     lock_key: "rql:lock:your_lockname", # acquired lock key
-    #     acq_id: "rql:acq:process_id/thread_id", # lock acquier identifier
-    #     ts: 123456789.2649841, # <locked at> time stamp (epoch, seconds.microseconds)
-    #     ini_ttl: 123456789, # initial lock key ttl (milliseconds),
-    #     rem_ttl: 123456789, # remaining lock key ttl (milliseconds)
+    #     'lock_key' => "rql:lock:your_lockname", # acquired lock key
+    #     'acq_id' => "rql:acq:process_id/thread_id", # lock acquier identifier
+    #     'ts' => 123456789.2649841, # <locked at> time stamp (epoch, seconds.microseconds)
+    #     'ini_ttl' => 123456789, # initial lock key ttl (milliseconds),
+    #     'rem_ttl' => 123456789, # remaining lock key ttl (milliseconds)
     #   }
     #
     # @api private
@@ -43,13 +43,12 @@ module RedisQueuedLocks::Acquier::LockInfo
           # NOTE: the result of MULTI-command is an array of results of each internal command
           #   - result[0] (HGETALL) (Hash<String,String>)
           #   - result[1] (PTTL) (Integer)
-          {
-            lock_key: lock_key,
-            acq_id: hget_cmd_res['acq_id'],
-            ts: Float(hget_cmd_res['ts']),
-            ini_ttl: Integer(hget_cmd_res['ini_ttl']),
-            rem_ttl: ((pttl_cmd_res == -1) ? Infinity : pttl_cmd_res)
-          }
+          hget_cmd_res.tap do |lock_data|
+            lock_data['lock_key'] = lock_key
+            lock_data['ts'] = Float(lock_data['ts'])
+            lock_data['ini_ttl'] = Integer(lock_data['ini_ttl'])
+            lock_data['rem_ttl'] = ((pttl_cmd_res == -1) ? Infinity : pttl_cmd_res)
+          end
         end
       end
     end

data/lib/redis_queued_locks/acquier/queue_info.rb

@@ -12,13 +12,13 @@ module RedisQueuedLocks::Acquier::QueueInfo
     #
     # @param redis_client [RedisClient]
     # @param lock_name [String]
-    # @return [Hash<Symbol,String|Array<Hash<Symbol,String|Float>>,NilClass]
+    # @return [Hash<String|Array<Hash<String,String|Numeric>>,NilClass]
     #   - `nil` is returned when lock queue does not exist;
     #   - result format: {
-    #     lock_queue: "rql:lock_queue:your_lock_name", # lock queue key in redis,
+    #     "lock_queue" => "rql:lock_queue:your_lock_name", # lock queue key in redis,
     #     queue: [
-    #       { acq_id: "rql:acq:process_id/thread_id", score: 123 },
-    #       { acq_id: "rql:acq:process_id/thread_id", score: 456 },
+    #       { "acq_id" => "rql:acq:process_id/thread_id", "score" => 123 },
+    #       { "acq_id" => "rql:acq:process_id/thread_id", "score" => 456 },
     #     ] # ordered set (by score) with information about an acquier and their position in queue
     #   }
     #
@@ -38,8 +38,8 @@ module RedisQueuedLocks::Acquier::QueueInfo
       if exists_cmd_res == 1
         # NOTE: queue existed during the piepline invocation
         {
-          lock_queue: lock_key_queue,
-          queue: zrange_cmd_res.map { |val| { acq_id: val[0], score: val[1] } }
+          'lock_queue' => lock_key_queue,
+          'queue' => zrange_cmd_res.map { |val| { 'acq_id' => val[0], 'score' => val[1] } }
         }
       else
         # NOTE: queue did not exist during the pipeline invocation

data/lib/redis_queued_locks/client.rb

@@ -93,8 +93,9 @@ class RedisQueuedLocks::Client
   #   already obtained;
   #   - Should the logic exit immidietly after the first try if the lock was obtained
   #   by another process while the lock request queue was initially empty;
-  # @option metadata [NilClass,Any]
-  #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
+  # @option meta [NilClass,Hash<String|Symbol,Any>]
+  #   - A custom metadata wich will be passed to the lock data in addition to the existing data;
+  #   - Metadata can not contain reserved lock data keys;
   # @option logger [::Logger,#debug]
   #   - Logger object used from the configuration layer (see config[:logger]);
   #   - See `RedisQueuedLocks::Logging::VoidLogger` for example;
@@ -102,6 +103,9 @@ class RedisQueuedLocks::Client
   #   - should be logged the each try of lock acquiring (a lot of logs can
   #     be generated depending on your retry configurations);
   #   - see `config[:log_lock_try]`;
+  # @option instrument [NilClass,Any]
+  #    - Custom instrumentation data wich will be passed to the instrumenter's payload
+  #      with :instrument key;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -122,9 +126,10 @@ class RedisQueuedLocks::Client
     raise_errors: false,
     fail_fast: false,
     identity: uniq_identity,
-    metadata: nil,
+    meta: nil,
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
+    instrument: nil,
     &block
   )
     RedisQueuedLocks::Acquier::AcquireLock.acquire_lock(
@@ -145,9 +150,10 @@ class RedisQueuedLocks::Client
       instrumenter: config[:instrumenter],
       identity:,
       fail_fast:,
-      metadata:,
+      meta:,
       logger: config[:logger],
       log_lock_try: config[:log_lock_try],
+      instrument:,
       &block
     )
   end
@@ -167,9 +173,10 @@ class RedisQueuedLocks::Client
     retry_jitter: config[:retry_jitter],
     fail_fast: false,
     identity: uniq_identity,
-    metadata: nil,
+    meta: nil,
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
+    instrument: nil,
     &block
   )
     lock(
@@ -184,7 +191,8 @@ class RedisQueuedLocks::Client
       raise_errors: true,
       identity:,
       fail_fast:,
-      metadata:,
+      meta:,
+      instrument:,
       &block
     )
   end
@@ -224,7 +232,7 @@ class RedisQueuedLocks::Client
   end
 
   # @param lock_name [String]
-  # @return [Hash,NilClass]
+  # @return [Hash<String,String|Numeric>,NilClass]
   #
   # @api public
   # @since 0.1.0
@@ -233,7 +241,7 @@ class RedisQueuedLocks::Client
   end
 
   # @param lock_name [String]
-  # @return [Hash,NilClass]
+  # @return [Hash<String|Array<Hash<String,String|Numeric>>,NilClass]
   #
   # @api public
   # @since 0.1.0

data/lib/redis_queued_locks/resource.rb

@@ -82,6 +82,20 @@ module RedisQueuedLocks::Resource
       Time.now.to_f - queue_ttl
     end
 
+    # @param acquier_position [Float]
+    #   A time (epoch, seconds.microseconds) that represents
+    #   the acquier position in lock request queue.
+    # @parma queue_ttl [Integer]
+    #   In second.
+    # @return [Boolean]
+    #   Is the lock request time limit has reached or not.
+    #
+    # @api private
+    # @since 0.1.0
+    def dead_score_reached?(acquier_position, queue_ttl)
+      (acquier_position + queue_ttl) < Time.now.to_f
+    end
+
     # @param lock_queue [String]
     # @return [String]
     #

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.29
+  version: 0.0.32
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-23 00:00:00.000000000 Z
+date: 2024-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client