redis_queued_locks 0.0.21 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ea008491f8c631aea2677c6571a206db919c0ca5d599b58adc37fa82c372145
-  data.tar.gz: 41e5bece44a3b1af1031d28a4d7bfe480641151573b97c89d62841f296cbc3ca
+  metadata.gz: 4360a9af038cc33ca36215d729558bab6810b9c5a4fec7f31df6ca2871b7dd80
+  data.tar.gz: 10b80a0f389994fde9a4815c3a5031ae85cee3c61d9c2a02e85d80146208bb99
 SHA512:
-  metadata.gz: cf96a4535a3fa8f6c7a62797805263e7957f198997213df65c164b9261d5199526f7dbc6e2a3f5e13a912e79cc7cd718ed193b0f197586cd03f1f3f95d958fca
-  data.tar.gz: 46726b0d18cd73d108b57b34872f1369ab63771a7d6c899aee021ab628ced537e6e0a7e255aecee259b902d682f5d13a12519dcc7033b786ef832c035a61f12a
+  metadata.gz: 362e7708a37f8716217e08117f072ef34d14886677379d28bef08f80c1a1a82e1309509dfc5fe4f748a3a10268bf340087c83e797ebcd72cb8172594352fb23d
+  data.tar.gz: 32a0943ee8c80b8ed745dff8eeea748c2289008d8fb00d3e20c7b464ef14a4d21158066e548bb86cfebc73c5d61a365289b49ae8061bc3ea0339ad7bb3c9894d

data/CHANGELOG.md

@@ -1,8 +1,12 @@
 ## [Unreleased]
 
+## [0.0.22] - 2024-03-21
+### Added
+- Logging infrastructure. Initial implementation includes the only debugging features.
+
 ## [0.0.21] - 2024-03-19
 ### Changed
-- `RedisQueuedLocks::Acquier` refactirngs;
+- Refactored `RedisQueuedLocks::Acquier`;
 
 ## [0.0.20] - 2024-03-14
 ### Added

data/README.md

@@ -134,6 +134,16 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - it is calculated once per `RedisQueudLocks::Client` instance;
   # - expects the proc object;
   config.uniq_identifier = -> { RedisQueuedLocks::Resource.calc_uniq_identity }
+
+  # (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'"
+  #   - 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'"
+  # - by default uses VoidLogger that does nothing;
+  config.logger = RedisQueuedLocks::Logging::VoidLogger
 end
 ```
 
@@ -581,6 +591,7 @@ Detalized event semantics and payload structure:
   - 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;

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

@@ -3,7 +3,11 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
+  # @since 0.1.0
+  extend RedisQueuedLocks::Utilities
+
   # @param redis [RedisClient] Redis connection manager.
+  # @param 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.
@@ -13,7 +17,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   #
   # @api private
   # @since 0.1.0
-  def yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
+  def yield_with_expire(redis, logger, lock_key, 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 }
@@ -23,6 +27,9 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
       end
     end
   ensure
+    run_non_critical do
+      logger.debug("[redis_queued_locks.expire_lock] lock_key => '#{lock_key}'")
+    end
     redis.call('EXPIRE', lock_key, '0')
   end
 

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -69,6 +69,9 @@ 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]);
+    #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -96,6 +99,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       identity:,
       fail_fast:,
       metadata:,
+      logger:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -127,6 +131,13 @@ module RedisQueuedLocks::Acquier::AcquireLock
       }
       acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
 
+      run_non_critical do
+        logger.debug(
+          "[redis_queued_locks.start_lock_obtaining] " \
+          "lock_key => '#{lock_key}'"
+        )
+      end
+
       # Step 2: try to lock with timeout
       with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
         acq_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
@@ -153,15 +164,25 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
           # Step 2.1: analyze an acquirement attempt
           if ok
+            run_non_critical do
+              logger.debug(
+                "[redis_queued_locks.lock_obtained] " \
+                "lock_key => '#{result[:lock_key]}'" \
+                "acq_time => #{acq_time} (ms)"
+              )
+            end
+
             # Step X (instrumentation): lock obtained
-            instrumenter.notify('redis_queued_locks.lock_obtained', {
-              lock_key: result[:lock_key],
-              ttl: result[:ttl],
-              acq_id: result[:acq_id],
-              ts: result[:ts],
-              acq_time: acq_time,
-              meta: metadata
-            })
+            run_non_critical do
+              instrumenter.notify('redis_queued_locks.lock_obtained', {
+                lock_key: result[:lock_key],
+                ttl: result[:ttl],
+                acq_id: result[:acq_id],
+                ts: result[:ts],
+                acq_time: acq_time,
+                meta: metadata
+              })
+            end
 
             # Step 2.1.a: successfully acquired => build the result
             acq_process[:lock_info] = {
@@ -225,7 +246,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, lock_key, timed, ttl_shift, ttl, &block)
+            yield_with_expire(redis, logger, lock_key, 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/acquier/extend_lock_ttl.rb

@@ -7,11 +7,12 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @param redis_client [RedisClient]
     # @param lock_name [String]
     # @param milliseconds [Integer]
+    # @param logger [#debug]
     # @return [?]
     #
     # @api private
     # @since 0.1.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
       # TODO: realize
     end
   end

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -17,12 +17,15 @@ 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]
+    #   - Logger object used from `configuration` layer (see config[:logger]);
+    #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
     #   Format: { ok: true/false, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 0.1.0
-    def release_all_locks(redis, batch_size, instrumenter)
+    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

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -20,12 +20,15 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   The lock name that should be released.
     # @param isntrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @param logger [#debug]
+    #   - Logger object used from `configuration` layer (see config[:logger]);
+    #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
     #   Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
     #
     # @api private
     # @since 0.1.0
-    def release_lock(redis, lock_name, instrumenter)
+    def release_lock(redis, lock_name, instrumenter, logger)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
 

data/lib/redis_queued_locks/client.rb

@@ -9,18 +9,16 @@ class RedisQueuedLocks::Client
 
   configuration do
     setting :retry_count, 3
-    setting :retry_delay, 200 # NOTE: milliseconds
-    setting :retry_jitter, 25 # NOTE: milliseconds
-    setting :try_to_lock_timeout, 10 # NOTE: seconds
-    setting :default_lock_ttl, 5_000 # NOTE: milliseconds
-    setting :default_queue_ttl, 15 # NOTE: seconds
+    setting :retry_delay, 200 # NOTE: in milliseconds
+    setting :retry_jitter, 25 # NOTE: in milliseconds
+    setting :try_to_lock_timeout, 10 # NOTE: in seconds
+    setting :default_lock_ttl, 5_000 # NOTE: in milliseconds
+    setting :default_queue_ttl, 15 # NOTE: in seconds
     setting :lock_release_batch_size, 100
     setting :key_extraction_batch_size, 500
     setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
     setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
-
-    # TODO: setting :logger, Logger.new(IO::NULL)
-    # TODO: setting :debug, true/false
+    setting :logger, RedisQueuedLocks::Logging::VoidLogger
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -30,6 +28,7 @@ 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)
   end
 
@@ -136,6 +135,7 @@ class RedisQueuedLocks::Client
       identity:,
       fail_fast:,
       metadata:,
+      logger: config[:logger],
       &block
     )
   end
@@ -186,7 +186,8 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier::ReleaseLock.release_lock(
       redis_client,
       lock_name,
-      config[:instrumenter]
+      config[:instrumenter],
+      config[:logger]
     )
   end
 
@@ -233,7 +234,12 @@ class RedisQueuedLocks::Client
   # @api public
   # @since 0.1.0
   def extend_lock_ttl(lock_name, milliseconds)
-    RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(redis_client, lock_name)
+    RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
+      redis_client,
+      lock_name,
+      milliseconds,
+      config[:logger]
+    )
   end
 
   # @option batch_size [Integer]
@@ -246,7 +252,8 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
-      config[:instrumenter]
+      config[:instrumenter],
+      config[:logger]
     )
   end
 

data/lib/redis_queued_locks/instrument/active_support.rb

@@ -8,7 +8,7 @@ module RedisQueuedLocks::Instrument::ActiveSupport
     # @param payload [Hash<String|Symbol,Any>]
     # @return [void]
     #
-    # @api private
+    # @api public
     # @since 0.1.0
     def notify(event, payload = {})
       ::ActiveSupport::Notifications.instrument(event, payload)

data/lib/redis_queued_locks/instrument/void_notifier.rb

@@ -8,7 +8,7 @@ module RedisQueuedLocks::Instrument::VoidNotifier
     # @param payload [Hash<String|Symbol,Any>]
     # @return [void]
     #
-    # @api private
+    # @api public
     # @since 0.1.0
     def notify(event, payload = {}); end
   end

data/lib/redis_queued_locks/instrument.rb

@@ -25,10 +25,10 @@ module RedisQueuedLocks::Instrument
         m_obj = instrumenter.method(:notify)
         m_sig = m_obj.parameters
 
-        f_prm = m_sig[0][0]
-        s_prm = m_sig[1][0]
-
         if m_sig.size == 2
+          f_prm = m_sig[0][0]
+          s_prm = m_sig[1][0]
+
           # rubocop:disable Layout/MultilineOperationIndentation
           # NOTE: check the signature vairants
           f_prm == :req && s_prm == :req ||

data/lib/redis_queued_locks/logging/void_logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+module RedisQueuedLocks::Logging::VoidLogger
+  class << self
+    # @api public
+    # @since 0.1.0
+    def warn(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def unknown(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def log(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def info(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def error(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def fatal(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def debug(progname = nil, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def add(*, &block); end
+
+    # @api public
+    # @since 0.1.0
+    def <<(message); end
+  end
+end

data/lib/redis_queued_locks/logging.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+module RedisQueuedLocks::Logging
+  require_relative 'logging/void_logger'
+
+  class << self
+    # @param logger [#debug]
+    # @return [Boolean]
+    #
+    # @api public
+    # @since 0.1.0
+    def valid_interface?(logger)
+      return true if logger.is_a?(::Logger)
+
+      # NOTE: should provide `#debug` method.
+      return false unless logger.respond_to?(:debug)
+
+      # NOTE:
+      #   `#debug` method should have appropriated signature `(progname, &block)`
+      #   Required method signature (progname, &block):
+      #     => [[:opt, :progname], [:block, :block]]
+      #     => [[:req, :progname], [:block, :block]]
+      #     => [[:opt, :progname]]
+      #     => [[:req, :progname]]
+      #     => [[:rest], [:block, :block]]
+      #     => [[:rest]]
+
+      m_obj = logger.method(:debug)
+      m_sig = m_obj.parameters
+
+      if m_sig.size == 2
+        # => [[:opt, :progname], [:block, :block]]
+        # => [[:req, :progname], [:block, :block]]
+        # => [[:rest], [:block, :block]]
+        f_prm = m_sig[0][0]
+        s_prm = m_sig[1][0]
+
+        # rubocop:disable Layout/MultilineOperationIndentation
+        f_prm == :opt && s_prm == :block ||
+        f_prm == :req && s_prm == :block ||
+        f_prm == :rest && s_prm == :block
+        # rubocop:enable Layout/MultilineOperationIndentation
+      elsif m_sig.size == 1
+        # => [[:opt, :progname]]
+        # => [[:req, :progname]]
+        # => [[:rest]]
+        prm = m_sig[0][0]
+
+        prm == :opt || prm == :req || prm == :rest
+      else
+        false
+      end
+    end
+  end
+end

data/lib/redis_queued_locks/version.rb

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

data/lib/redis_queued_locks.rb

@@ -4,6 +4,7 @@ require 'redis-client'
 require 'qonfig'
 require 'timeout'
 require 'securerandom'
+require 'logger'
 
 # @api public
 # @since 0.1.0
@@ -11,6 +12,7 @@ module RedisQueuedLocks
   require_relative 'redis_queued_locks/version'
   require_relative 'redis_queued_locks/errors'
   require_relative 'redis_queued_locks/utilities'
+  require_relative 'redis_queued_locks/logging'
   require_relative 'redis_queued_locks/data'
   require_relative 'redis_queued_locks/debugger'
   require_relative 'redis_queued_locks/resource'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.21
+  version: 0.0.22
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-19 00:00:00.000000000 Z
+date: 2024-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -79,6 +79,8 @@ files:
 - lib/redis_queued_locks/instrument.rb
 - lib/redis_queued_locks/instrument/active_support.rb
 - lib/redis_queued_locks/instrument/void_notifier.rb
+- lib/redis_queued_locks/logging.rb
+- lib/redis_queued_locks/logging/void_logger.rb
 - lib/redis_queued_locks/resource.rb
 - lib/redis_queued_locks/utilities.rb
 - lib/redis_queued_locks/version.rb