redis_queued_locks 0.0.37 → 0.0.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6417546d24eb5f2c7bbfffeebb506054fd96fc65ec0464ebbfdcf05db5b2972
-  data.tar.gz: e6ddf10eeb79dbdb9f2ed05480fa57423851cdd1ab9864a56b0d917c3c1aa533
+  metadata.gz: df02925d34d26ec7181e33c783a2c368f84e2981a1b6249da100f0fc19515d5c
+  data.tar.gz: 4ae526151618eecba0ac733677e2d3e5dd8ae2558058c8407b693a6085e712d0
 SHA512:
-  metadata.gz: ebeb82df02afcc0a9cc9838769a20e027ab54704bb91ab84942ba71b04175554888cbd9448abc2fb5abf5343a43dfb7905f0d1e831a5566614fd67b6a8f5391b
-  data.tar.gz: 9052a8ed7a3a056787184e100e06a98920f4d758e169515e47021b6fdafadf69056304e0177070bd050d9586bff990f2bae394d9a27490df9bd3fe949d509ea0
+  metadata.gz: 44f6546626e39b0fd1378a2cdcd8d72f2d394cba7478cbd2594c3b50b60cd2d484d0d4fca584a09391f5a5cc68c275b3b8f5c7fdf52d0c8c55976518bf3fe03b
+  data.tar.gz: 6c1251c02654e7b816e993d8e4a24c7cbf92ea0d908ba2d3efb60b99f711d0c7ce93902199f29c40e35b42fac2d76de4693380b72d01df0192c43e630e2cdf8e

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.0.39] - 2024-03-31
+### Added
+- Logging:
+  - added new log `[redis_queued_locks.fail_fast_or_limits_reached__dequeue]`;
+- Client:
+  - `#extend_lock_ttl` implementation;
+### Changed
+- Removed `RadisQueuedLocks::Debugger.debug(...)` injections;
+- Instrumentation:
+  - the `:at` payload field of `"redis_queued_locks.explicit_lock_release"` event and
+  `"redis_queued_locks.explicit_all_locks_release"` event is changed from `Integer` to `Float`
+  in order to reflect micro/nano seconds too for more accurate time value;
+- Lock information:
+  - the lock infrmation extracting now uses `RedisClient#pipelined` instead of `RedisClient#mutli` cuz
+    it is more reasonable for information-oriented logic (the queue information extraction works via `pipelined` invocations for example);
+- Logging:
+  - log message is used as a `message` (not `pragma`) according to `Logger#debug` signature;
+
+## [0.0.38] - 2024-03-28
+### Changed
+- Minor update (dropped useless constant);
+
 ## [0.0.37] - 2024-03-28
 ### Changed
 - `#queues_info`: `:contains` is renamed to `:reqeusts` in order to reflect it's domain area;

data/README.md

@@ -1,16 +1,17 @@
-# RedisQueuedLocks
+# RedisQueuedLocks · [![Gem Version](https://badge.fury.io/rb/redis_queued_locks.svg)](https://badge.fury.io/rb/redis_queued_locks)
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
 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.
+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) (with requeue capabilities) which guarantees the request queue will never be stacked.
 
 ---
 
 ## Table of Contents
 
 - [Requirements](#requirements)
+- [Experience](#experience)
 - [Algorithm](#algorithm)
 - [Installation](#installation)
 - [Setup](#setup)
@@ -30,6 +31,7 @@ Each lock request is put into the request queue (each lock is hosted by it's own
   - [keys](#keys---get-list-of-taken-locks-and-queues)
   - [locks_info](#locks_info---get-list-of-locks-with-their-info)
   - [queues_info](#queues_info---get-list-of-queues-with-their-info)
+  - [clear_dead_requests](#clear_dead_requests)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
@@ -43,6 +45,14 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 - Redis Version: `~> 7.x`;
 - Redis Protocol: `RESP3`;
+- gem `redis-client`: `~> 0.20`;
+
+---
+
+### Experience
+
+- Battle-tested on huge ruby projects in production: `~1500` locks-per-second are obtained and released on an ongoing basis;
+- Works well with `hiredis` driver enabled (it is enabled by default on our projects where `redis_queued_locks` are used);
 
 ---
 
@@ -156,6 +166,7 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[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");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached__dequeue] (logs "lock_key", "queue_ttl", "acq_id");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
@@ -170,8 +181,8 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[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");
+  #   - "[redis_queued_locks.try_lock.exit__lock_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.obtain_free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
   config.log_lock_try = false
 end
 ```
@@ -194,6 +205,7 @@ end
 - [keys](#keys---get-list-of-taken-locks-and-queues)
 - [locks_info](#locks_info---get-list-of-locks-with-their-info)
 - [queues_info](#queues_info---get-list-of-queues-with-their-info)
+- [clear_dead_requests](#clear_dead_requests)
 
 ---
 
@@ -336,7 +348,7 @@ 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 data (`Hash<String,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;
@@ -385,7 +397,7 @@ rql.lock_info("your_lock_name")
   - score is represented as a timestamp when the lock request was made;
   - 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 data (`Hash<String,String|Array<Hash<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);
@@ -493,7 +505,31 @@ Return:
 
 #### #extend_lock_ttl
 
-- soon
+- Extend the lock's TTL (in milliseconds);
+- returns `{ ok: true, result: :ttl_extended }` when ttl is extended;
+- returns `{ ok: false, result: :async_expire_or_no_lock }` when lock not found or lock is expired during
+  some steps of invocation (see **Important** section below);
+- **Important**:
+  - the method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension;
+  - the method consists of two commands:
+    - (1) read current pttl;
+    - (2) set new ttl that is calculated as "current pttl + additional milliseconds";
+  - what can happen during these steps:
+    - lock is expired between commands or before the first command;
+    - lock is expired before the second command;
+    - lock is expired AND newly acquired by another process (so you will extend the
+      totally new lock with fresh PTTL);
+  - use it at your own risk and consider the async nature when calling this method;
+
+```ruby
+rql.extend_lock_ttl("my_lock", 5_000) # NOTE: add 5_000 milliseconds
+
+# => `ok` case
+{ ok: true, result: :ttl_extended }
+
+# => `failed` case
+{ ok: false, result: :async_expire_or_no_lock }
+```
 
 ---
 
@@ -505,7 +541,7 @@ Return:
   - `:with_info` - `Boolean` - `false` by default (for details see [#locks_info](#locks_info---get-list-of-locks-with-their-info));
 - returns:
   - `Set<String>` (for `with_info: false`);
-  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See `#locks_info` for details;
+  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See [#locks_info](#locks_info---get-list-of-locks-with-their-info) for details;
 
 ```ruby
 rql.locks # or rql.locks(scan_size: 123)
@@ -532,10 +568,10 @@ rql.locks # or rql.locks(scan_size: 123)
 - uses redis `SCAN` under the hood;
 - accepts
   - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
-  - `:with_info` - `Boolean` - `false` by default (for details see [queues_info](#queues_info---get-list-of-queues-with-their-info));
+  - `:with_info` - `Boolean` - `false` by default (for details see [#queues_info](#queues_info---get-list-of-queues-with-their-info));
 - returns:
   - `Set<String>` (for `with_info: false`);
-  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See `#locks_info` for details;
+  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See [#locks_info](#locks_info---get-list-of-locks-with-their-info) for details;
 
 ```ruby
 rql.queues # or rql.queues(scan_size: 123)
@@ -645,11 +681,18 @@ rql.queues_info # or rql.qeuues_info(scan_size: 123)
      {"acq_id"=>"rql:acq:38529/4460/4480/4360/66093702f24a3129", "score"=>1711606640.540808}]},
   ...}>
 ```
+---
+
+#### #clear_dead_requests
+
+- soon
 
 ---
 
 ## Instrumentation
 
+- [Instrumentation Events](#instrumentation-events)
+
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
 
 Instrumenter object should provide `notify(event, payload)` method with the following signarue:
@@ -701,7 +744,7 @@ Detalized event semantics and payload structure:
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
   - payload:
-    - `:at` - `integer`/`epoch` - the time when the lock was released;
+    - `:at` - `float`/`epoch` - the time when the lock was released;
     - `:rel_time` - `float`/`milliseconds` - time spent on lock releasing;
     - `:lock_key` - `string` - released lock (lock name);
     - `:lock_key_queue` - `string` - released lock queue (lock queue name);
@@ -709,7 +752,7 @@ Detalized event semantics and payload structure:
   - an event signalizes about the explicit all locks release (invoked via `RedisQueuedLock#clear_locks`);
   - payload:
     - `:rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
-    - `:at` - `integer`/`epoch` - the time when the operation has ended;
+    - `:at` - `float`/`epoch` - the time when the operation has ended;
     - `:rel_keys` - `integer` - released redis keys count (`released queue keys` + `released lock keys`);
 
 ---
@@ -717,7 +760,7 @@ Detalized event semantics and payload structure:
 ## Roadmap
 
 - Semantic Error objects for unexpected Redis errors;
-- `100%` test coverage;
+- better specs :) with 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). It only makes sense for non-`timed` locks;
@@ -726,8 +769,8 @@ Detalized event semantics and payload structure:
 - structured logging (separated docs);
 - GitHub Actions CI;
 - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
-- better code stylization and interesting refactorings;
-- dead queue keys cleanup (empty queues);
+- better code stylization and interesting refactorings (observers);
+- dead requests cleanup;
 - statistics with UI;
 
 ---

data/Rakefile

@@ -2,11 +2,20 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
+require 'rubocop'
 require 'rubocop/rake_task'
+require 'rubocop-performance'
+require 'rubocop-rspec'
+require 'rubocop-rake'
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  config_path = File.expand_path(File.join('.rubocop.yml'), __dir__)
+  t.options = ['--config', config_path]
+  t.requires << 'rubocop-rspec'
+  t.requires << 'rubocop-performance'
+  t.requires << 'rubocop-rake'
+end
 
-RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:rspec)
 
-task default: %i[spec rubocop]
+task default: :rspec

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

@@ -42,12 +42,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
     if log_lock_try
       run_non_critical do
-        logger.debug(
+        logger.debug do
           "[redis_queued_locks.try_lock.start] " \
           "lock_key => '#{lock_key}' " \
           "queue_ttl => #{queue_ttl} " \
           "acq_id => '#{acquier_id}'"
-        )
+        end
       end
     end
 
@@ -55,12 +55,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     result = redis.with do |rconn|
       if log_lock_try
         run_non_critical do
-          logger.debug(
+          logger.debug do
             "[redis_queued_locks.try_lock.rconn_fetched] " \
             "lock_key => '#{lock_key}' " \
             "queue_ttl => #{queue_ttl} " \
             "acq_id => '#{acquier_id}'"
-          )
+          end
         end
       end
 
@@ -74,25 +74,21 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           inter_result = :fail_fast_no_try
         else
           # Step 1: add an acquier to the lock acquirement queue
-          res = rconn.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
+          rconn.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
 
           if log_lock_try
             run_non_critical do
-              logger.debug(
+              logger.debug do
                 "[redis_queued_locks.try_lock.acq_added_to_queue] " \
                 "lock_key => '#{lock_key}' " \
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
-              )
+              end
             end
           end
 
-          RedisQueuedLocks.debug(
-            "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
-          )
-
           # Step 2.1: drop expired acquiers from the lock queue
-          res = rconn.call(
+          rconn.call(
             'ZREMRANGEBYSCORE',
             lock_key_queue,
             '-inf',
@@ -101,58 +97,44 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
           if log_lock_try
             run_non_critical do
-              logger.debug(
+              logger.debug do
                 "[redis_queued_locks.try_lock.remove_expired_acqs] " \
                 "lock_key => '#{lock_key}' " \
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
-              )
+              end
             end
           end
 
-          RedisQueuedLocks.debug(
-            "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
-          )
-
           # Step 3: get the actual acquier waiting in the queue
           waiting_acquier = Array(rconn.call('ZRANGE', lock_key_queue, '0', '0')).first
 
           if log_lock_try
             run_non_critical do
-              logger.debug(
+              logger.debug do
                 "[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}'"
-              )
+              end
             end
           end
 
-          RedisQueuedLocks.debug(
-            "Step №3: какой процесс в очереди сейчас ждет. " \
-            "[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(
+                logger.debug do
                   "[redis_queued_locks.try_lock.exit__queue_ttl_reached] " \
                   "lock_key => '#{lock_key}' " \
                   "queue_ttl => #{queue_ttl} " \
                   "acq_id => '#{acquier_id}'"
-                )
+                end
               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?
           elsif waiting_acquier != acquier_id
@@ -160,59 +142,41 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
             if log_lock_try
               run_non_critical do
-                logger.debug(
+                logger.debug do
                   "[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}' " \
                   "<current_lock_data> => <<#{rconn.call('HGETALL', lock_key).to_h}>>"
-                )
+                end
               end
             end
 
-            RedisQueuedLocks.debug(
-              "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
-              "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
-            )
-
             inter_result = :acquier_is_not_first_in_queue
           else
             # NOTE: our time has come! let's try to acquire the lock!
 
-            # Step 5: check if the our lock is already acquired
+            # Step 5: find the lock -> check if the our lock is already acquired
             locked_by_acquier = rconn.call('HGET', lock_key, 'acq_id')
 
-            # rubocop:disable Layout/LineLength
-            RedisQueuedLocks.debug(
-              "Ste №5: Ищем требуемый лок. " \
-              "[HGET<#{lock_key}>: " \
-              "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
-            )
-            # rubocop:enable Layout/LineLength
-
             if locked_by_acquier
               # Step ROLLBACK 2: required lock is stil acquired. retry!
 
               if log_lock_try
                 run_non_critical do
-                  logger.debug(
-                    "[redis_queued_locks.try_lock.exit__still_obtained] " \
+                  logger.debug do
+                    "[redis_queued_locks.try_lock.exit__lock_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}' " \
                     "<current_lock_data> => <<#{rconn.call('HGETALL', lock_key).to_h}>>"
-                  )
+                  end
                 end
               end
 
-              RedisQueuedLocks.debug(
-                "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
-                "[Занят процессом: #{locked_by_acquier}]"
-              )
-
               inter_result = :lock_is_still_acquired
             else
               # NOTE: required lock is free and ready to be acquired! acquire!
@@ -220,16 +184,6 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               # Step 6.1: remove our acquier from waiting queue
               transact.call('ZREM', lock_key_queue, acquier_id)
 
-              RedisQueuedLocks.debug(
-                'Step №4: Забираем наш текущий процесс из очереди. [ZREM]'
-              )
-
-              # rubocop:disable Layout/LineLength
-              RedisQueuedLocks.debug(
-                "===> <FINAL> Step №6: закрепляем лок за процессом [HSET<#{lock_key}>: #{acquier_id}]"
-              )
-              # rubocop:enable Layout/LineLength
-
               # Step 6.2: acquire a lock and store an info about the acquier
               transact.call(
                 'HSET',
@@ -245,12 +199,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
               if log_lock_try
                 run_non_critical do
-                  logger.debug(
-                    "[redis_queued_locks.try_lock.run__free_to_acquire] " \
+                  logger.debug do
+                    "[redis_queued_locks.try_lock.obtain_free_to_acquire] " \
                     "lock_key => '#{lock_key}' " \
                     "queue_ttl => #{queue_ttl} " \
                     "acq_id => '#{acquier_id}'"
-                  )
+                  end
                 end
               end
             end
@@ -279,7 +233,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       #   => (*) at this moment we accept that all comamnds are completed successfully;
       #   => (!) need to analyze:
       #   1. zrem shoud return ? (?)
-      #   2. hset should return 3 as minimum (lock key is added to the redis as a hashmap with 3 fields as minimum)
+      #   2. hset should return 3 as minimum
+      #      (lock key is added to the redis as a hashmap with 3 fields as minimum)
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.d: locked! :) let's go! => successfully acquired
@@ -296,18 +251,26 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
 
   # @param redis [RedisClient]
+  # @param logger [::Logger,#debug]
+  # @param lock_key [String]
   # @param lock_key_queue [String]
+  # @param queue_ttl [Integer]
   # @param acquier_id [String]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
-  def dequeue_from_lock_queue(redis, lock_key_queue, acquier_id)
+  def dequeue_from_lock_queue(redis, logger, lock_key, lock_key_queue, queue_ttl, acquier_id)
     result = redis.call('ZREM', lock_key_queue, acquier_id)
 
-    RedisQueuedLocks.debug(
-      "Step ~ [СМЕРТЬ ПРОЦЕССА]: [#{acquier_id} :: #{lock_key_queue}] РЕЗУЛЬТАТ: #{result}"
-    )
+    run_non_critical do
+      logger.debug do
+        "[redis_queued_locks.fail_fast_or_limits_reached__dequeue] " \
+        "lock_key => '#{lock_key}' " \
+        "queue_ttl => '#{queue_ttl}' " \
+        "acq_id => '#{acquier_id}'"
+      end
+    end
 
     RedisQueuedLocks::Data[ok: true, result: result]
   end

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

@@ -40,12 +40,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
     end
   ensure
     run_non_critical do
-      logger.debug(
+      logger.debug do
         "[redis_queued_locks.expire_lock] " \
         "lock_key => '#{lock_key}' " \
         "queue_ttl => #{queue_ttl} " \
         "acq_id => '#{acquier_id}'"
-      )
+      end
     end
     redis.call('EXPIRE', lock_key, '0')
   end

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -165,15 +165,24 @@ module RedisQueuedLocks::Acquier::AcquireLock
         hold_time: nil, # NOTE: in milliseconds
         rel_time: nil # NOTE: in milliseconds
       }
-      acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
+
+      acq_dequeue = proc do
+        dequeue_from_lock_queue(
+          redis, logger,
+          lock_key,
+          lock_key_queue,
+          queue_ttl,
+          acquier_id
+        )
+      end
 
       run_non_critical do
-        logger.debug(
+        logger.debug do
           "[redis_queued_locks.start_lock_obtaining] " \
           "lock_key => '#{lock_key}' " \
           "queue_ttl => #{queue_ttl} " \
           "acq_id => '#{acquier_id}'"
-        )
+        end
       end
 
       # Step 2: try to lock with timeout
@@ -183,12 +192,12 @@ module RedisQueuedLocks::Acquier::AcquireLock
         # Step 2.1: caclically try to obtain the lock
         while acq_process[:should_try]
           run_non_critical do
-            logger.debug(
+            logger.debug do
               "[redis_queued_locks.start_try_to_lock_cycle] " \
               "lock_key => '#{lock_key}' " \
               "queue_ttl => #{queue_ttl} " \
               "acq_id => '{#{acquier_id}'"
-            )
+            end
           end
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
@@ -197,12 +206,12 @@ module RedisQueuedLocks::Acquier::AcquireLock
             acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
 
             run_non_critical do
-              logger.debug(
+              logger.debug do
                 "[redis_queued_locks.dead_score_reached__reset_acquier_position] " \
                 "lock_key => '#{lock_key} " \
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
-              )
+              end
             end
           end
 
@@ -230,13 +239,13 @@ module RedisQueuedLocks::Acquier::AcquireLock
           # Step 2.1: analyze an acquirement attempt
           if ok
             run_non_critical do
-              logger.debug(
+              logger.debug do
                 "[redis_queued_locks.lock_obtained] " \
                 "lock_key => '#{result[:lock_key]}' " \
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}' " \
                 "acq_time => #{acq_time} (ms)"
-              )
+              end
             end
 
             # Step X (instrumentation): lock obtained

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -3,17 +3,35 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::ExtendLockTTL
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  EXTEND_LOCK_PTTL = <<~LUA_SCRIPT.strip.tr("\n", '').freeze
+    local new_lock_pttl = redis.call("PTTL", KEYS[1]) + ARGV[1];
+    return redis.call("PEXPIRE", KEYS[1], new_lock_pttl);
+  LUA_SCRIPT
+
   class << self
     # @param redis_client [RedisClient]
     # @param lock_name [String]
     # @param milliseconds [Integer]
-    # @param logger [::Logger,#debug]
-    # @return [?]
+    # @return [Hash<Symbol,Boolean|Symbol>]
     #
     # @api private
     # @since 0.1.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
-      # TODO: realize
+    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+
+      # NOTE: EVAL signature -> <lua script>, (keys number), *(keys), *(arguments)
+      result = redis_client.call('EVAL', EXTEND_LOCK_PTTL, 1, lock_key, milliseconds)
+      # TODO: upload scripts to the redis
+
+      if result == 1
+        RedisQueuedLocks::Data[ok: true, result: :ttl_extended]
+      else
+        RedisQueuedLocks::Data[ok: false, result: :async_expire_or_no_lock]
+      end
     end
   end
 end

data/lib/redis_queued_locks/acquier/lock_info.rb

@@ -21,9 +21,9 @@ module RedisQueuedLocks::Acquier::LockInfo
     def lock_info(redis_client, lock_name)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 
-      result = redis_client.multi(watch: [lock_key]) do |transact|
-        transact.call('HGETALL', lock_key)
-        transact.call('PTTL', lock_key)
+      result = redis_client.pipelined do |pipeline|
+        pipeline.call('HGETALL', lock_key)
+        pipeline.call('PTTL', lock_key)
       end
 
       if result == nil

data/lib/redis_queued_locks/acquier/locks.rb

@@ -3,12 +3,6 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::Locks
-  # @return [Hash]
-  #
-  # @api private
-  # @since 0.1.0
-  NO_LOCK_INFO = {}.freeze
-
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
@@ -56,9 +50,9 @@ module RedisQueuedLocks::Acquier::Locks
         # Step X: iterate each lock and extract their info
         lock_keys.each do |lock_key|
           # Step 1: extract lock info from redis
-          lock_info = redis_client.multi(watch: [lock_key]) do |transact|
-            transact.call('HGETALL', lock_key)
-            transact.call('PTTL', lock_key)
+          lock_info = redis_client.pipelined do |pipeline|
+            pipeline.call('HGETALL', lock_key)
+            pipeline.call('PTTL', lock_key)
           end.yield_self do |result| # Step 2: format the result
             # Step 2.X: lock is released
             if result == nil

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -28,7 +28,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     def release_all_locks(redis, batch_size, instrumenter, logger)
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
-      time_at = Time.now.to_i
+      time_at = Time.now.to_f
       rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil(2)
 

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -34,7 +34,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
 
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_lock(redis, lock_key, lock_key_queue) => { ok:, result: }
-      time_at = Time.now.to_i
+      time_at = Time.now.to_f
       rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil(2)
 

data/lib/redis_queued_locks/client.rb

@@ -249,9 +249,22 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier::QueueInfo.queue_info(redis_client, lock_name)
   end
 
+  # This method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension.
+  # So the methid is spliited into the two commands:
+  #   (1) read current pttl
+  #   (2) set new ttl that is calculated as "current pttl + additional milliseconds"
+  # What can happen during these steps
+  # - lock is expired between commands or before the first command;
+  # - lock is expired before the second command;
+  # - lock is expired AND newly acquired by another process (so you will extend the
+  #   totally new lock with fresh PTTL);
+  # Use it at your own risk and consider async nature when calling this method.
+  #
   # @param lock_name [String]
   # @param milliseconds [Integer] How many milliseconds should be added.
-  # @return [?]
+  # @return [Hash<Symbol,Boolean|Symbol>]
+  #   - { ok: true, result: :ttl_extended }
+  #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
   # @since 0.1.0
@@ -259,8 +272,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
       lock_name,
-      milliseconds,
-      config[:logger]
+      milliseconds
     )
   end
 

data/lib/redis_queued_locks/data.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-# NOTE: wiill be rewritten with Ruby's 3.2 "Data" class;
 class RedisQueuedLocks::Data < Hash
 end

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.37
+  version: 0.0.39
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-28 00:00:00.000000000 Z
+date: 2024-03-31 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.5.1
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.