redis_queued_locks 0.0.27 → 0.0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d7bd4d48e34f520e1e7675030a15a346eca0f89429b500b7937ef36cf8107b
-  data.tar.gz: 7c331e2a5d728a78ce8009bc6d1e97621bab61ad336683e45b52063f2fff1715
+  metadata.gz: 3137184f5a89b895fe347d8080957e08a57974e91d5a68189d0eb157afd7c3eb
+  data.tar.gz: 7b059f5de5cde2af1634eed3aeae540afd7edfc5ba564781789649098e53e0a1
 SHA512:
-  metadata.gz: 33491d78f0a847f90ed27792ae3edd90388d78fb4098cd6eae00b85ea13c5353523f252f1cf83e01918bce502b3ad5735825e5f642122b0a15f6d301df12f5f1
-  data.tar.gz: a18017f9c1bc2559fbd6c723ce1fccc99c7041f6952e535dba31e14a5029abf43c215c6abcd0aaf514d4d670614882255e2b356c3c214a83b77265a826fe16e0
+  metadata.gz: 4821b6c0fc142d90fae314aa11c92069be9223cc4a61be077ff6e19278fae97f920d31b590c5688f3614159a2f5c9d9d1792d8a6aee50f51d7b24f83ea1a9298
+  data.tar.gz: 80a0de485f263459c52d230cc0e604d0c742db235a6a9b57053cc84001e9e146cfc35b9c31aff5e1ef5a2796692559f95fe94db39350720277fb219ef95a2685

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.0.29] - 2024-03-23
+### Added
+- Logging: more detailed logs to `RedisQueuedLocks::Acquier::AcquireLock::TryToLock`;
+
+## [0.0.28] - 2024-03-21
+### Added
+- Logging: added `acq_id` to every log message;
+- Logging: updated documentation;
+
 ## [0.0.27] - 2024-03-21
 ### Changed
 - Better acquier position accuracy: acquier position in lock queue

data/README.md

@@ -139,15 +139,18 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - 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'"
-  #   - finish of the lock obtaining: "[redis_queued_locks.lock_obtained] lock_key => 'rql:lock:your_lock' acq_time => 123.456 (ms)"
-  #   - start of the lock expiration after `yield`: "[redis_queud_locks.expire_lock] lock_key => 'rql:lock:your_lock'"
+  #   - 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'"
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
   # (default: false)
-  # - should be logged the each try of lock acquiring (a lot of logs can be generated depending on your retry configurations);
-  # - if logger is not cofnigured this option does not lead to any effect;
+  # - 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'"
+  # - if logger is not configured this option does not lead to any effect;
   config.log_lock_try = false
 end
 ```
@@ -597,23 +600,21 @@ Detalized event semantics and payload structure:
 
 ## Roadmap
 
-- **Major**
-  - Semantic Error objects for unexpected Redis errors;
-  - `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);
-  - an ability to add custom metadata to the lock and an ability to read this data;
-  - lock prioritization;
-  - support for LIFO strategy;
-  - structured logging;
-- **Minor**
-  - GitHub Actions CI;
-  - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
-  - better code stylization and interesting refactorings;
-  - lock queue expiration (dead queue cleanup);
-  - support for `Dragonfly` DB backend;
-  - support for `Garnet` DB backend;
+- Semantic Error objects for unexpected Redis errors;
+- `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);
+- an ability to add custom metadata to the lock and an ability to read this data;
+- lock prioritization;
+- support for LIFO strategy;
+- structured logging;
+- GitHub Actions CI;
+- `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
+- better code stylization and interesting refactorings;
+- dead queue cleanup;
+- support for `Dragonfly` DB backend;
+- support for `Garnet` DB backend;
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 0.1.0
-# rubocop:disable Metrics/ModuleLength
+# rubocop:disable Metrics/ModuleLength, Metrics/BlockNesting
 module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @since 0.1.0
   extend RedisQueuedLocks::Utilities
@@ -41,7 +41,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     if log_lock_try
       run_non_critical do
         logger.debug(
-          "[redis_queued_locks.try_lock_start] " \
+          "[redis_queued_locks.try_lock.start] " \
           "lock_key => '#{lock_key}' " \
           "acq_id => '#{acquier_id}'"
         )
@@ -53,7 +53,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       if log_lock_try
         run_non_critical do
           logger.debug(
-            "[redis_queued_locks.try_lock_rconn_fetched] " \
+            "[redis_queued_locks.try_lock.rconn_fetched] " \
             "lock_key => '#{lock_key}' " \
             "acq_id => '#{acquier_id}'"
           )
@@ -63,12 +63,22 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       rconn.multi(watch: [lock_key]) do |transact|
         # Fast-Step X0: fail-fast check
         if fail_fast && rconn.call('HGET', lock_key, 'acq_id')
-          # Fast-Step X1: is lock already obtained. fail fast - no try.
+          # Fast-Step X1: is lock already obtained. fail fast leads to "no try".
           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)
 
+          if log_lock_try
+            run_non_critical do
+              logger.debug(
+                "[redis_queued_locks.try_lock.acq_added_to_queue] " \
+                "lock_key => '#{lock_key}' " \
+                "acq_id => '#{acquier_id}'"
+              )
+            end
+          end
+
           RedisQueuedLocks.debug(
             "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
           )
@@ -81,6 +91,16 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
           )
 
+          if log_lock_try
+            run_non_critical do
+              logger.debug(
+                "[redis_queued_locks.try_lock.remove_expired_acqs] " \
+                "lock_key => '#{lock_key}' " \
+                "acq_id => '#{acquier_id}'"
+              )
+            end
+          end
+
           RedisQueuedLocks.debug(
             "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
           )
@@ -88,6 +108,17 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           # 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(
+                "[redis_queued_locks.try_lock.get_first_from_queue] " \
+                "lock_key => '#{lock_key}' " \
+                "acq_id => '#{acquier_id}' " \
+                "first_acq_id_in_queue => '#{waiting_acquier}'"
+              )
+            end
+          end
+
           RedisQueuedLocks.debug(
             "Step №3: какой процесс в очереди сейчас ждет. " \
             "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
@@ -97,6 +128,17 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           unless waiting_acquier == acquier_id
             # Step ROLLBACK 1.1: our time hasn't come yet. retry!
 
+            if log_lock_try
+              run_non_critical do
+                logger.debug(
+                  "[redis_queued_locks.try_lock.exit__no_first] " \
+                  "lock_key => '#{lock_key}' " \
+                  "acq_id => '#{acquier_id}' " \
+                  "first_acq_id_in_queue => '#{waiting_acquier}'"
+                )
+              end
+            end
+
             RedisQueuedLocks.debug(
               "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
               "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
@@ -120,6 +162,18 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             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] " \
+                    "lock_key => '#{lock_key}' " \
+                    "acq_id => '#{acquier_id}' " \
+                    "first_acq_id_in_queue => '#{waiting_acquier}' " \
+                    "locked_by_acq_id => '#{locked_by_acquier}'"
+                  )
+                end
+              end
+
               RedisQueuedLocks.debug(
                 "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
                 "[Занят процессом: #{locked_by_acquier}]"
@@ -153,6 +207,16 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
               # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
               transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
+
+              if log_lock_try
+                run_non_critical do
+                  logger.debug(
+                    "[redis_queued_locks.try_lock.run__free_to_acquire] " \
+                    "lock_key => '#{lock_key}' " \
+                    "acq_id => '#{acquier_id}'"
+                  )
+                end
+              end
             end
           end
         end
@@ -210,4 +274,4 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     RedisQueuedLocks::Data[ok: true, result: result]
   end
 end
-# rubocop:enable Metrics/ModuleLength
+# rubocop:enable Metrics/ModuleLength, Metrics/BlockNesting

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

@@ -9,6 +9,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   # @param redis [RedisClient] Redis connection manager.
   # @param logger [::Logger,#debug] Logger object.
   # @param lock_key [String] Lock key to be expired.
+  # @param acquier_id [String] Acquier identifier.
   # @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".
@@ -17,7 +18,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   #
   # @api private
   # @since 0.1.0
-  def yield_with_expire(redis, logger, lock_key, timed, ttl_shift, ttl, &block)
+  def yield_with_expire(redis, logger, lock_key, acquier_id, timed, ttl_shift, ttl, &block)
     if block_given?
       if timed && ttl != nil
         timeout = ((ttl - ttl_shift) / 1000.0).yield_self { |time| (time < 0) ? 0.0 : time }
@@ -28,7 +29,11 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
     end
   ensure
     run_non_critical do
-      logger.debug("[redis_queued_locks.expire_lock] lock_key => '#{lock_key}'")
+      logger.debug(
+        "[redis_queued_locks.expire_lock] " \
+        "lock_key => '#{lock_key}' " \
+        "acq_id => '#{acquier_id}'"
+      )
     end
     redis.call('EXPIRE', lock_key, '0')
   end

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -176,7 +176,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               logger.debug(
                 "[redis_queued_locks.lock_obtained] " \
                 "lock_key => '#{result[:lock_key]}' " \
-                "acq_id: => '#{acquier_id}' " \
+                "acq_id => '#{acquier_id}' " \
                 "acq_time => #{acq_time} (ms)"
               )
             end
@@ -255,7 +255,7 @@ 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, timed, ttl_shift, ttl, &block)
+            yield_with_expire(redis, logger, lock_key, acquier_id, timed, ttl_shift, ttl, &block)
           ensure
             acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             acq_process[:hold_time] = (

data/lib/redis_queued_locks/version.rb

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

metadata

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