redis_queued_locks 0.0.22 → 0.0.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4360a9af038cc33ca36215d729558bab6810b9c5a4fec7f31df6ca2871b7dd80
-  data.tar.gz: 10b80a0f389994fde9a4815c3a5031ae85cee3c61d9c2a02e85d80146208bb99
+  metadata.gz: b0c873b666d2c9f618789e6ef957e1ce7375da840bcbc1ce797d9e457bcc7d72
+  data.tar.gz: 9f9c4637fae7ca1a1e8bdc247e23f5c11977af7962f545ae084d05126106dad0
 SHA512:
-  metadata.gz: 362e7708a37f8716217e08117f072ef34d14886677379d28bef08f80c1a1a82e1309509dfc5fe4f748a3a10268bf340087c83e797ebcd72cb8172594352fb23d
-  data.tar.gz: 32a0943ee8c80b8ed745dff8eeea748c2289008d8fb00d3e20c7b464ef14a4d21158066e548bb86cfebc73c5d61a365289b49ae8061bc3ea0339ad7bb3c9894d
+  metadata.gz: 06c3a4ee60f8c5da6d9272ed99bff10315496c79e6c922431529b7f34da896e17fb08c73b389080f82c54e3714d89780950517e3beff469661bbbf6c4bdbaf0e
+  data.tar.gz: a0d7c9287c0a22923f2ddd4573ec6be63c0e274cff23fb5b2744b9cbd44368b7803b1ced3ffe9eefc53f0f2f23729177641535835bb6f97ede5f79074a308c4f

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.0.24] - 2024-03-21
+### Added
+- An optional ability to log each try of lock obtaining (see `RedisQueuedLocks::Acquier::AcquireLock::TryToLock.try_to_lock`);
+
+## [0.0.23] - 2024-03-21
+### Changed
+- Composed redis commands are invoked on the one conenction
+  (instead of mutiple connection fetchiong from redis connection pool on each redis command);
+
 ## [0.0.22] - 2024-03-21
 ### Added
 - Logging infrastructure. Initial implementation includes the only debugging features.

data/README.md

@@ -144,6 +144,11 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - start of the lock expiration after `yield`: "[redis_queud_locks.expire_lock] lock_key => 'rql:lock:your_lock'"
   # - 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;
+  config.log_lock_try = false
 end
 ```
 
@@ -187,6 +192,8 @@ def lock(
   fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   metadata: nil,
+  logger: config[:logger],
+  log_lock_try: config[:log_lock_try],
   &block
 )
 ```
@@ -224,6 +231,12 @@ def lock(
     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;
+- `logger` - `[::Logger,#debug]`
+  - Logger object used from the configuration layer (see config[:logger]);
+  - See `RedisQueuedLocks::Logging::VoidLogger` for example;
+- `log_lock_try` - `[Boolean]`
+  - 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]`;
 - `block` - `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
@@ -278,6 +291,8 @@ def lock!(
   identity: uniq_identity,
   fail_fast: false,
   metadata: nil,
+  logger: config[:logger],
+  log_lock_try: config[:log_lock_try],
   &block
 )
 ```

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

@@ -2,8 +2,14 @@
 
 # @api private
 # @since 0.1.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
+  # @since 0.1.0
+  extend RedisQueuedLocks::Utilities
+
   # @param redis [RedisClient]
+  # @param logger [::Logger,#debug]
+  # @param log_lock_try [Boolean]
   # @param lock_key [String]
   # @param lock_key_queue [String]
   # @param acquier_id [String]
@@ -18,6 +24,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
+    logger,
+    log_lock_try,
     lock_key,
     lock_key_queue,
     acquier_id,
@@ -30,96 +38,114 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     inter_result = nil
     timestamp = nil
 
+    if log_lock_try
+      run_non_critical do
+        logger.debug("[redis_queued_locks.try_lock_start] lock_key => '#{lock_key}'")
+      end
+    end
+
     # Step 0: watch the lock key changes (and discard acquirement if lock is already acquired)
-    result = redis.multi(watch: [lock_key]) do |transact|
-      # Fast-Step X0: fail-fast check
-      if fail_fast && redis.call('HGET', lock_key, 'acq_id')
-        # Fast-Step X1: is lock already obtained. fail fast - no try.
-        inter_result = :fail_fast_no_try
-      else
-        # Step 1: add an acquier to the lock acquirement queue
-        res = redis.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
-
-        RedisQueuedLocks.debug(
-          "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
-        )
-
-        # Step 2.1: drop expired acquiers from the lock queue
-        res = redis.call(
-          'ZREMRANGEBYSCORE',
-          lock_key_queue,
-          '-inf',
-          RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
-        )
-
-        RedisQueuedLocks.debug(
-          "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
-        )
-
-        # Step 3: get the actual acquier waiting in the queue
-        waiting_acquier = Array(redis.call('ZRANGE', lock_key_queue, '0', '0')).first
-
-        RedisQueuedLocks.debug(
-          "Step №3: какой процесс в очереди сейчас ждет. " \
-          "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
-        )
-
-        # Step 4: check the actual acquier: is it ours? are we aready to lock?
-        unless waiting_acquier == acquier_id
-          # Step ROLLBACK 1.1: our time hasn't come yet. retry!
+    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}'")
+        end
+      end
+
+      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.
+          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)
 
           RedisQueuedLocks.debug(
-            "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
-            "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
+            "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
           )
 
-          inter_result = :acquier_is_not_first_in_queue
-        else
-          # NOTE: our time has come! let's try to acquire the lock!
+          # Step 2.1: drop expired acquiers from the lock queue
+          res = rconn.call(
+            'ZREMRANGEBYSCORE',
+            lock_key_queue,
+            '-inf',
+            RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
+          )
 
-          # Step 5: check if the our lock is already acquired
-          locked_by_acquier = redis.call('HGET', lock_key, 'acq_id')
+          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
 
           RedisQueuedLocks.debug(
-            "Ste №5: Ищем требуемый лок. " \
-            "[HGET<#{lock_key}>: " \
-            "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
+            "Step №3: какой процесс в очереди сейчас ждет. " \
+            "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
           )
 
-          if locked_by_acquier
-            # Step ROLLBACK 2: required lock is stil acquired. retry!
+          # Step 4: check the actual acquier: is it ours? are we aready to lock?
+          unless waiting_acquier == acquier_id
+            # Step ROLLBACK 1.1: our time hasn't come yet. retry!
 
             RedisQueuedLocks.debug(
-              "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
-              "[Занят процессом: #{locked_by_acquier}]"
+              "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
+              "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
             )
 
-            inter_result = :lock_is_still_acquired
+            inter_result = :acquier_is_not_first_in_queue
           else
-            # NOTE: required lock is free and ready to be acquired! acquire!
-
-            # Step 6.1: remove our acquier from waiting queue
-            transact.call('ZPOPMIN', lock_key_queue, '1')
+            # NOTE: our time has come! let's try to acquire the lock!
 
-            RedisQueuedLocks.debug(
-              'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
-            )
+            # Step 5: check if the our lock is already acquired
+            locked_by_acquier = rconn.call('HGET', lock_key, 'acq_id')
 
+            # rubocop:disable Layout/LineLength
             RedisQueuedLocks.debug(
-              "===> <FINAL> Step №6: закрепляем лок за процессом [HSET<#{lock_key}>: #{acquier_id}]"
+              "Ste №5: Ищем требуемый лок. " \
+              "[HGET<#{lock_key}>: " \
+              "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
             )
-
-            # Step 6.2: acquire a lock and store an info about the acquier
-            transact.call(
-              'HSET',
-              lock_key,
-              'acq_id', acquier_id,
-              'ts', (timestamp = Time.now.to_i),
-              'ini_ttl', ttl
-            )
-
-            # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
-            transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
+            # rubocop:enable Layout/LineLength
+
+            if locked_by_acquier
+              # Step ROLLBACK 2: required lock is stil acquired. retry!
+
+              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!
+
+              # Step 6.1: remove our acquier from waiting queue
+              transact.call('ZPOPMIN', lock_key_queue, '1')
+
+              RedisQueuedLocks.debug(
+                'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
+              )
+
+              # 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',
+                lock_key,
+                'acq_id', acquier_id,
+                'ts', (timestamp = Time.now.to_i),
+                'ini_ttl', ttl
+              )
+
+              # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
+              transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
+            end
           end
         end
       end
@@ -176,3 +202,4 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     RedisQueuedLocks::Data[ok: true, result: result]
   end
 end
+# rubocop:enable Metrics/ModuleLength

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

@@ -7,7 +7,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   extend RedisQueuedLocks::Utilities
 
   # @param redis [RedisClient] Redis connection manager.
-  # @param logger [#debug] Logger object.
+  # @param logger [::Logger,#debug] Logger object.
   # @param lock_key [String] Lock key to be expired.
   # @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.

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -69,9 +69,13 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   already obtained.
     # @option metadata [NilClass,Any]
     #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
-    # @option logger [#debug]
-    #   - Logger object used from `configuration` layer (see config[:logger]);
+    # @option logger [::Logger,#debug]
+    #   - Logger object used from the configuration layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @option log_lock_try [Boolean]
+    #   - 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]`;
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -100,6 +104,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       fail_fast:,
       metadata:,
       logger:,
+      log_lock_try:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -146,6 +151,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
         while acq_process[:should_try]
           try_to_lock(
             redis,
+            logger,
+            log_lock_try,
             lock_key,
             lock_key_queue,
             acquier_id,

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -7,7 +7,7 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @param redis_client [RedisClient]
     # @param lock_name [String]
     # @param milliseconds [Integer]
-    # @param logger [#debug]
+    # @param logger [::Logger,#debug]
     # @return [?]
     #
     # @api private

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -17,7 +17,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   The number of lock keys that should be released in a time.
     # @param isntrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @param logger [#debug]
+    # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
@@ -57,26 +57,28 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     # @api private
     # @since 0.1.0
     def fully_release_all_locks(redis, batch_size)
-      result = redis.pipelined do |pipeline|
-        # Step A: release all queus and their related locks
-        redis.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
-          count: batch_size
-        ) do |lock_queue|
-          # TODO: reduce unnecessary iterations
-          pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
-          pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
-        end
+      result = redis.with do |rconn|
+        rconn.pipelined do |pipeline|
+          # Step A: release all queus and their related locks
+          rconn.scan(
+            'MATCH',
+            RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+            count: batch_size
+          ) do |lock_queue|
+            # TODO: reduce unnecessary iterations
+            pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
+            pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
+          end
 
-        # Step B: release all locks
-        redis.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::LOCK_PATTERN,
-          count: batch_size
-        ) do |lock_key|
-          # TODO: reduce unnecessary iterations
-          pipeline.call('EXPIRE', lock_key, '0')
+          # Step B: release all locks
+          rconn.scan(
+            'MATCH',
+            RedisQueuedLocks::Resource::LOCK_PATTERN,
+            count: batch_size
+          ) do |lock_key|
+            # TODO: reduce unnecessary iterations
+            pipeline.call('EXPIRE', lock_key, '0')
+          end
         end
       end
 

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -20,7 +20,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   The lock name that should be released.
     # @param isntrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @param logger [#debug]
+    # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
@@ -65,9 +65,11 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @api private
     # @since 0.1.0
     def fully_release_lock(redis, lock_key, lock_key_queue)
-      result = redis.multi do |transact|
-        transact.call('ZREMRANGEBYSCORE', lock_key_queue, '-inf', '+inf')
-        transact.call('EXPIRE', lock_key, '0')
+      result = redis.with do |rconn|
+        rconn.multi do |transact|
+          transact.call('ZREMRANGEBYSCORE', lock_key_queue, '-inf', '+inf')
+          transact.call('EXPIRE', lock_key, '0')
+        end
       end
 
       RedisQueuedLocks::Data[ok: true, result:]

data/lib/redis_queued_locks/client.rb

@@ -19,6 +19,7 @@ class RedisQueuedLocks::Client
     setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
     setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
     setting :logger, RedisQueuedLocks::Logging::VoidLogger
+    setting :log_lock_try, false
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -28,8 +29,9 @@ class RedisQueuedLocks::Client
     validate('default_queue_ttl', :integer)
     validate('lock_release_batch_size', :integer)
     validate('instrumenter') { |val| RedisQueuedLocks::Instrument.valid_interface?(val) }
-    validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
     validate('uniq_identifier', :proc)
+    validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
+    validate('log_lock_try', :boolean)
   end
 
   # @return [RedisClient]
@@ -93,6 +95,13 @@ class RedisQueuedLocks::Client
   #   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 logger [::Logger,#debug]
+  #   - Logger object used from the configuration layer (see config[:logger]);
+  #   - See `RedisQueuedLocks::Logging::VoidLogger` for example;
+  # @option log_lock_try [Boolean]
+  #   - 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]`;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -114,6 +123,8 @@ class RedisQueuedLocks::Client
     fail_fast: false,
     identity: uniq_identity,
     metadata: nil,
+    logger: config[:logger],
+    log_lock_try: config[:log_lock_try],
     &block
   )
     RedisQueuedLocks::Acquier::AcquireLock.acquire_lock(
@@ -136,6 +147,7 @@ class RedisQueuedLocks::Client
       fail_fast:,
       metadata:,
       logger: config[:logger],
+      log_lock_try: config[:log_lock_try],
       &block
     )
   end
@@ -156,6 +168,8 @@ class RedisQueuedLocks::Client
     fail_fast: false,
     identity: uniq_identity,
     metadata: nil,
+    logger: config[:logger],
+    log_lock_try: config[:log_lock_try],
     &block
   )
     lock(

data/lib/redis_queued_locks/logging.rb

@@ -6,7 +6,7 @@ module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
 
   class << self
-    # @param logger [#debug]
+    # @param logger [::Logger,#debug]
     # @return [Boolean]
     #
     # @api public

data/lib/redis_queued_locks/version.rb

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

metadata

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