redis_queued_locks 0.0.30 → 0.0.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0920957ed856cf515d2867ecd6ed7b1911ba53466822f09d5bd98386a5be4296'
-  data.tar.gz: 587fa64039e85a633fc2c65d5c0b012d7bfb29b9ccd25177e0895deb33850c38
+  metadata.gz: 43854a2842911dcf40e95329b2631bc6c76cdaff0cd204fb57eff55c0ee461aa
+  data.tar.gz: c361d55a71ac4c71d307fca4a7182069d055e302ec7b65274bcbc1a4ede6f768
 SHA512:
-  metadata.gz: 388e0d43c66464672bbe019dc0f26e3bac44be0cc3e5dcdb502ccd9b2d0b82931de2608c6b7219b2c190b9024197a0cbf1263a7cc7d4f8ed6568480ce6120930
-  data.tar.gz: 56158aca2424c21fc3fcbeebbd33625559aceca82143c2e18700334c6485e919d4005f4391ba3a07b0839e9122f57b9c5d223ebfd4bc38bdd4f61b58bc94f34f
+  metadata.gz: 6887f12891fce49f878427b501980695872e304c1429331d23b251d2f66f2db1f07a0994952f0b4ad6d9ec9b81ea769eaefe09ab1bef0c1abcadc9770ef38344
+  data.tar.gz: aa2f6d2cfbe72dd6bf5c637f5538ce1df7c8415579505f765b3016a4c243abc52cd1db246f51abba7efa51abef123d577e26bfee992a5484208cb1416ca00f50

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.0.33] - 2024-03-26
+### Added
+- Logging: added current lock data info to the detailed `#try_to_lock` log to the cases when lock is still obtained. It is suitable
+  when you pass a custom metadata with lock obtainer (for example: the current string of code) and want to see this information
+  in logs when you can not acquire the concrete lock long time;
+
+## [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

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.
 
@@ -138,18 +140,27 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # (default: RedisQueuedLocks::Logging::VoidLogger)
   # - the logger object;
   # - should implement `debug(progname = nil, &block)` (minimal requirement) or be an instance of Ruby's `::Logger` class/subclass;
-  # - at this moment the only debug logs are realised in 3 cases:
-  #   - start of lock obtaining: "[redis_queud_locks.start_lock_obtaining] lock_key => 'rql:lock:your_lock' acq_id => 'rql:acq:54307/3620/3640/3540/c1799ede93'"
-  #   - finish of the lock obtaining: "[redis_queued_locks.lock_obtained] lock_key => 'rql:lock:your_lock' acq_id => 'rql:acq:54307/3620/3640/3540/c1799ede93' acq_time => 123.456 (ms)"
-  #   - start of the lock expiration after `yield`: "[redis_queud_locks.expire_lock] lock_key => 'rql:lock:your_lock' acq_id => 'rql:acq:54307/3620/3640/3540/c1799ede93'"
+  # - at this moment the only debug logs are realised in following cases:
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lockkey", "queue_ttl", "acq_id", "acq_time");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
   # (default: false)
-  # - should be logged the each internal try-retry lock acquire (a lot of logs can be generated depending on your retry configurations);
-  # - it adds 2 cases to the log in addition to the existing 3:
-  #   - start of a try: "[redis_queud_locks.try_lock_start] lock_key => 'rql:lock:your_lock' acq_id => 'rql:acq:54307/3620/3640/3540/c1799ede93'"
-  #   - redis connection is feteched from the pool after "start of a try": "[redis_queued_locks.try_lock_rconn_fetched] lock_key => 'rql:lock:your_lock' acq_id => 'rql:acq:54307/3620/3640/3540/c1799ede93'"
+  # - adds additional debug logs;
+  # - enables additional logs for each internal try-retry lock acquiring (a lot of logs can be generated depending on your retry configurations);
+  # - it adds following logs in addition to the existing:
+  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id)";
+  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.run__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
   # - if logger is not configured this option does not lead to any effect;
   config.log_lock_try = false
 end
@@ -194,7 +205,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 +244,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 +308,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 +325,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 +375,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 +393,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 +640,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 +650,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
@@ -44,7 +46,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           "[redis_queued_locks.try_lock.start] " \
           "lock_key => '#{lock_key}' " \
           "queue_ttl => #{queue_ttl} " \
-          "acq_id => '#{acquier_id}' "
+          "acq_id => '#{acquier_id}'"
         )
       end
     end
@@ -161,7 +163,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                   "lock_key => '#{lock_key}' " \
                   "queue_ttl => #{queue_ttl} " \
                   "acq_id => '#{acquier_id}' " \
-                  "first_acq_id_in_queue => '#{waiting_acquier}'"
+                  "first_acq_id_in_queue => '#{waiting_acquier}' " \
+                  "<current_lock_data> => <<#{rconn.call('HGETALL', lock_key).to_h}>>"
                 )
               end
             end
@@ -197,7 +200,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
                     "queue_ttl => #{queue_ttl} " \
                     "acq_id => '#{acquier_id}' " \
                     "first_acq_id_in_queue => '#{waiting_acquier}' " \
-                    "locked_by_acq_id => '#{locked_by_acquier}'"
+                    "locked_by_acq_id => '#{locked_by_acquier}' " \
+                    "<current_lock_data> => <<#{rconn.call('HGETALL', lock_key).to_h}>>"
                   )
                 end
               end
@@ -230,7 +234,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"

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

@@ -63,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,
@@ -185,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)
@@ -215,7 +247,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 acq_id: result[:acq_id],
                 ts: result[:ts],
                 acq_time: acq_time,
-                meta: metadata
+                instrument:
               })
             end
 
@@ -233,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
@@ -255,14 +288,16 @@ 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:
@@ -307,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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.30
+  version: 0.0.33
 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
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.1
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.