redis_queued_locks 0.0.0 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 612f9339ffba6231bcfe2277af85e2225346f6166eb5bb77da0f507beaeae888
-  data.tar.gz: 35229b1d26a17a9c46e39e565d11ec416ca0e173f57360765c064327ffa6390a
+  metadata.gz: e984603ea8f509f8e5f7f685c356d1f838b16bc950e1de83ff8f66e6afa83fcf
+  data.tar.gz: 1b2eee0f32c911caecf08214b2b404d620ffb10501ae72d7721235b64fc02362
 SHA512:
-  metadata.gz: 1fdb43047ee4b3ac72d28a244ddc9cb4d6b363ff3aa3852b3cc27cbb77ab0a159ef1a45e7eb13f4e4407449fc7b7383e1aac1775f5f739e6ae2e2fcacc5ced46
-  data.tar.gz: 2fbf7fb572005090140ccc9a972e4d84d5be0b1a9a2154fc37c1b04f2dcf44abb06ec6e530c1fa36be0f7ddb3795615f6d7626a224a9d3f3fe913cbf3362734f
+  metadata.gz: b7e2d574eeeff4a9a235f39ee25bde152880dcd12e7066196a8304e54098480ef05672edd89a6931ece225711b96602f23ce76304c555dbd623d30099e35ca0a
+  data.tar.gz: d7f5075bbf136e672ebb1632da5c6a78b2b72886bc1d5e8b0d9425cf38b14f5eef5a097fdc835c78f5f2d26885512279926a33bdbdb559151b875453d5312c9e

data/.rubocop.yml

@@ -5,7 +5,7 @@ inherit_gem:
     - lib/rubocop.rspec.yml
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.1
   NewCops: enable
   Include:
     - lib/**/*.rb
@@ -33,3 +33,6 @@ Metrics/AbcSize:
 
 Metrics/CyclomaticComplexity:
   Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.2.2
+3.1.2

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.0.2] - 2024-02-26
+### Added
+- Instrumentation events:
+  - `"redis_queued_locks.lock_obtained"`;
+  - `"redis_queued_locks.lock_hold_and_release"`;
+  - `"redis_queued_locks.explicit_lock_release"`;
+  - `"redis_queued_locks.explicit_all_locks_release"`;
+
+## [0.0.1] - 2024-02-26
+
+- Still the initial release version;
+- Downgrade the minimal Ruby version requirement from 3.2 to 3.1;
+
 ## [0.0.0] - 2024-02-25
 
 - Initial release

data/README.md

@@ -1,3 +1,43 @@
 # RedisQueuedLocks
 
 Distributed lock implementation with "lock acquisition queue" capabilities based on the Redis Database.
+
+## Instrumentation events
+
+- `"redis_queued_locks.lock_obtained"`
+  - a moment when the lock was obtained;
+  - payload:
+    - `ttl` - `integer`/`milliseconds` - lock ttl;
+    - `acq_id` - `string` - lock acquier identifier;
+    - `lock_key` - `string` - lock name;
+    - `ts` - `integer`/`epoch` - the time when the lock was obtaiend;
+    - `acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+- `"redis_queued_locks.lock_hold_and_release"`
+  - an event signalizes about the "hold+and+release" process
+    when the lock obtained and hold by the block of logic;
+  - payload:
+    - `hold_time` - `float`/`milliseconds` - lock hold time;
+    - `ttl` - `integer`/`milliseconds` - lock ttl;
+    - `acq_id` - `string` - lock acquier identifier;
+    - `lock_key` - `string` - lock name;
+    - `ts` - `integer`/`epoch` - the time when lock was obtained;
+    - `acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+    - `rel_time` - `float`/`milliseconds` - time spent on lock "holding + releasing";
+- `"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;
+    - `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);
+- `"redis_queued_locks.explicit_all_locks_release"`
+  - an event signalizes about the explicit all locks release (invoked viaa `RedisQueuedLock#clear_locks`);
+  - payload:
+    - `rel_time` - `float`/`milliseconds` - time when the locks was released
+    - `at` - `integer`/`epoch` - the time when the operation has ended;
+    - `rel_lock_cnt` - `integer` - released lock count;
+    - `rel_queue_cnt` - `integer` - released queue count;
+
+## Todo
+
+- CI (github actions);

data/lib/redis_queued_locks/acquier/release.rb

@@ -8,28 +8,40 @@ module RedisQueuedLocks::Acquier::Release
   # @param redis [RedisClient]
   # @param lock_key [String]
   # @param lock_key_queue [String]
-  # @return [void]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
   def fully_release_lock(redis, lock_key, lock_key_queue)
-    redis.multi do |transact|
+    result = redis.multi do |transact|
       transact.call('ZREMRANGEBYSCORE', lock_key_queue, '-inf', '+inf')
       transact.call('EXPIRE', lock_key, '0')
     end
+
+    { ok: true, result: }
   end
 
   # Release all locks: clear all lock queus and expire all locks.
   #
   # @param redis [RedisClient]
   # @param batch_size [Integer]
-  # @return [void]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
   def fully_release_all_locks(redis, batch_size)
+    rel_queue_cnt = 0
+    rel_lock_cnt = 0
+
     # Step A: release all queus and their related locks
-    redis.scan('MATCH', RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN) do |lock_queue|
+    redis.scan(
+      'MATCH',
+      RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+      count: batch_size
+    ) do |lock_queue|
+      rel_queue_cnt += 1
+      rel_lock_cnt += 1
+
       redis.pipelined do |pipeline|
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
         pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue))
@@ -38,9 +50,17 @@ module RedisQueuedLocks::Acquier::Release
 
     # Step B: release all locks
     redis.pipelined do |pipeline|
-      redis.scan('MATCH', RedisQueuedLocks::Resource::LOCK_PATTERN) do |lock_key|
+      rel_lock_cnt += 1
+
+      redis.scan(
+        'MATCH',
+        RedisQueuedLocks::Resource::LOCK_PATTERN,
+        count: batch_size
+      ) do |lock_key|
         pipeline.call('EXPIRE', lock_key, '0')
       end
     end
+
+    { ok: true, result: { rel_queue_cnt:, rel_lock_cnt: } }
   end
 end

data/lib/redis_queued_locks/acquier/try.rb

@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquier::Try
   #
   # @api private
   # @since 0.1.0
-  # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/MethodLength
   def try_to_lock(redis, lock_key, lock_key_queue, acquier_id, acquier_position, ttl, queue_ttl)
     # Step X: intermediate invocation results
     inter_result = nil
@@ -111,13 +111,13 @@ module RedisQueuedLocks::Acquier::Try
     when result == nil || (result.is_a?(::Array) && result.empty?)
       # Step 7.b: lock is already acquired durign the acquire race => failed to acquire
       { ok: false, result: :lock_is_acquired_during_acquire_race }
-    when result.is_a?(::Array) && result.size == 3 # NOTE: 3 is a count of lock commands
+    when result.is_a?(::Array) && result.size == 3 # NOTE: 3 is a count of redis lock commands
       # TODO:
       #   => (!) analyze the command result and do actions with the depending on it;
       #   => (*) at this moment we accept that all comamnds are completed successfully;
       #   => (!) need to analyze:
       #   1. zpopmin should return our process (array with <acq_id> and <score>)
-      #   2. hset should return 2 (lock key is added to the redis db with 2 fields)
+      #   2. hset should return 2 (lock key is added to the redis as a hashmap with 2 fields)
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.c: locked! :) let's go! => successfully acquired

data/lib/redis_queued_locks/acquier.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 0.1.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquier
   require_relative 'acquier/try'
   require_relative 'acquier/delay'
@@ -26,6 +27,7 @@ module RedisQueuedLocks::Acquier
   # @since 0.1.0
   REDIS_EXPIRATION_DEVIATION = 2 # NOTE: milliseconds
 
+  # rubocop:disable Metrics/ClassLength
   class << self
     # @param redis [RedisClient]
     #   Redis connection client.
@@ -35,10 +37,10 @@ module RedisQueuedLocks::Acquier
     #   The process that want to acquire the lock.
     # @option thread_id [Integer,String]
     #   The process's thread that want to acquire the lock.
-    # @option ttl [Integer]
-    #   Lock's time to live (in milliseconds).
+    # @option ttl [Integer,NilClass]
+    #   Lock's time to live (in milliseconds). Nil means "without timeout".
     # @option queue_ttl [Integer]
-    #   ?
+    #   Lifetime of the acuier's lock request. In seconds.
     # @option timeout [Integer]
     #   Time period whe should try to acquire the lock (in seconds).
     # @option retry_count [Integer]
@@ -47,6 +49,10 @@ module RedisQueuedLocks::Acquier
     #   A time-interval between the each retry (in milliseconds).
     # @option retry_jitter [Integer]
     #   Time-shift range for retry-delay (in milliseconds).
+    # @option raise_errors [Boolean]
+    #   Raise errors on exceptional cases.
+    # @option instrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [Hash<Symbol,Any>]
@@ -66,6 +72,8 @@ module RedisQueuedLocks::Acquier
       retry_count:,
       retry_delay:,
       retry_jitter:,
+      raise_errors:,
+      instrumenter:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -76,11 +84,22 @@ module RedisQueuedLocks::Acquier
       acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
 
       # Step X: intermediate result observer
-      acq_process = { lock_info: {}, should_try: true, tries: 0, acquired: false, result: nil }
+      acq_process = {
+        lock_info: {},
+        should_try: true,
+        tries: 0,
+        acquired: false,
+        result: nil,
+        acq_time: nil, # NOTE: in milliseconds
+        hold_time: nil, # NOTE: in milliseconds
+        rel_time: nil # NOTE: in milliseconds
+      }
       acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
 
       # Step 2: try to lock with timeout
-      with_timeout(timeout, lock_key, on_timeout: acq_dequeue) do
+      with_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
+        acq_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+
         # Step 2.1: caclically try to obtain the lock
         while acq_process[:should_try]
           try_to_lock(
@@ -93,15 +112,33 @@ module RedisQueuedLocks::Acquier
             queue_ttl
           ) => { ok:, result: }
 
+          acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          acq_time = ((acq_end_time - acq_start_time) * 1_000).ceil
+
           # Step X: save the intermediate results to the result observer
           acq_process[:result] = result
 
           # Step 2.1: analyze an acquirement attempt
           if ok
+            # 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
+            })
+
             # Step 2.1.a: successfully acquired => build the result
-            acq_process[:lock_info] = result
+            acq_process[:lock_info] = {
+              lock_key: result[:lock_key],
+              acq_id: result[:acq_id],
+              ts: result[:ts],
+              ttl: result[:ttl]
+            }
             acq_process[:acquired] = true
             acq_process[:should_try] = false
+            acq_process[:acq_time] = acq_time
           else
             # Step 2.1.b: failed acquirement => retry
             acq_process[:tries] += 1
@@ -125,7 +162,25 @@ module RedisQueuedLocks::Acquier
       if acq_process[:acquired]
         # Step 3.a: acquired successfully => run logic or return the result of acquirement
         if block_given?
-          yield_with_expire(redis, lock_key, &block)
+          begin
+            yield_with_expire(redis, lock_key, instrumenter, &block)
+          ensure
+            acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            acq_process[:hold_time] = ((
+              acq_process[:rel_time] - acq_process[:acq_time]
+            ) * 1000).ceil
+
+            # Step X (instrumentation): lock_hold_and_release
+            instrumenter.notify('redis_queued_locks.lock_hold_and_release', {
+              hold_time: acq_process[:hold_time],
+              rel_time: acq_process[:rel_time],
+              ttl: acq_process[:lock_info][:ttl],
+              acq_id: acq_process[:lock_info][:acq_id],
+              ts: acq_process[:lock_info][:ts],
+              lock_key: acq_process[:lock_info][:lock_key],
+              acq_time: acq_process[:acq_time]
+            })
+          end
         else
           { ok: true, result: acq_process[:lock_info] }
         end
@@ -146,15 +201,28 @@ module RedisQueuedLocks::Acquier
     #
     # @param redis [RedisClient] Redis connection client.
     # @param lock_name [String] The lock name that should be released.
+    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
     #
     # @api private
     # @since 0.1.0
-    def release_lock!(redis, lock_name)
+    def release_lock!(redis, lock_name, instrumenter)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
 
+      rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       result = fully_release_lock(redis, lock_key, lock_key_queue)
+      time_at = Time.now.to_i
+      rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil
+
+      instrumenter.notify('redis_queued_locks.explicit_lock_release', {
+        lock_key: lock_key,
+        lock_key_queue: lock_key_queue,
+        rel_time: rel_time,
+        at: time_at
+      })
+
       { ok: true, result: result }
     end
 
@@ -164,31 +232,54 @@ module RedisQueuedLocks::Acquier
     #
     # @param redis [RedisClient] Redis connection client.
     # @param batch_size [Integer] The number of lock keys that should be released in a time.
+    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
     #
     # @api private
     # @since 0.1.0
-    def release_all_locks!(redis, batch_size)
+    def release_all_locks!(redis, batch_size, instrumenter)
+      rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       result = fully_release_all_locks(redis, batch_size)
+      time_at = Time.now.to_i
+      rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil
+
+      instrumenter.notify('redis_queued_locks.explicit_all_locks_release', {
+        at: time_at,
+        rel_time: rel_time,
+        rel_lock_cnt: result[:rel_lock_cnt],
+        rel_queue_cnt: result[:rel_queue_cnt]
+      })
+
       { ok: true, result: result }
     end
 
     private
 
-    # @param timeout [Integer] Time period after which the logic will fail with timeout error.
-    # @param lock_key [String] Lock name.
-    # @option on_timeout [Proc,NilClass] Callback invoked on Timeout::Error.
+    # @param timeout [NilClass,Integer]
+    #   Time period after which the logic will fail with timeout error.
+    # @param lock_key [String]
+    #   Lock name.
+    # @param raise_errors [Boolean]
+    #   Raise erros on exceptional cases.
+    # @option on_timeout [Proc,NilClass]
+    #   Callback invoked on Timeout::Error.
     # @return [Any]
     #
     # @api private
     # @since 0.1.0
-    def with_timeout(timeout, lock_key, on_timeout: nil, &block)
+    def with_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
       ::Timeout.timeout(timeout, &block)
     rescue ::Timeout::Error
       on_timeout.call unless on_timeout == nil
-      raise(RedisQueuedLocks::LockAcquiermentTimeoutError, <<~ERROR_MESSAGE.strip)
-        Failed to acquire the lock "#{lock_key}" for the given timeout (#{timeout} seconds).
-      ERROR_MESSAGE
+
+      if raise_errors
+        raise(RedisQueuedLocks::LockAcquiermentTimeoutError, <<~ERROR_MESSAGE.strip)
+          Failed to acquire the lock "#{lock_key}" for the given timeout (#{timeout} seconds).
+        ERROR_MESSAGE
+      end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/client.rb

@@ -10,23 +10,25 @@ class RedisQueuedLocks::Client
     setting :retry_count, 3
     setting :retry_delay, 200 # NOTE: milliseconds
     setting :retry_jitter, 50 # NOTE: milliseconds
-    setting :acquire_timeout, 10 # NOTE: seconds
+    setting :default_timeout, 10 # NOTE: seconds
     setting :exp_precision, 1 # NOTE: milliseconds
     setting :default_lock_ttl, 10_000 # NOTE: milliseconds
     setting :default_queue_ttl, 5 # NOTE: seconds
     setting :lock_release_batch_size, 100
+    setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
 
     # TODO: setting :logger, Logger.new(IO::NULL)
     # TODO: setting :debug, true/false
 
-    validate 'retry_count', :integer
-    validate 'retry_delay', :integer
-    validate 'retry_jitter', :integer
-    validate 'acquire_timeout', :integer
-    validate 'exp_precision', :integer
-    validate 'default_lock_tt', :integer
-    validate 'default_queue_ttl', :integer
-    validate 'lock_release_batch_size', :integer
+    validate('retry_count', :integer)
+    validate('retry_delay', :integer)
+    validate('retry_jitter', :integer)
+    validate('default_timeout', :integer)
+    validate('exp_precision', :integer)
+    validate('default_lock_tt', :integer)
+    validate('default_queue_ttl', :integer)
+    validate('lock_release_batch_size', :integer)
+    validate('instrumenter') { |instr| RedisQueuedLocks::Instrument.valid_interface?(instr) }
   end
 
   # @return [RedisClient]
@@ -58,15 +60,19 @@ class RedisQueuedLocks::Client
   # @option ttl [Integer]
   #   Lock's time to live (in milliseconds).
   # @option queue_ttl [Integer]
-  #   ?
-  # @option timeout [Integer]
-  #   Time period whe should try to acquire the lock (in seconds).
+  #   Lifetime of the acuier's lock request. In seconds.
+  # @option timeout [Integer,NilClass]
+  #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout".
   # @option retry_count [Integer]
   #   How many times we should try to acquire a lock.
   # @option retry_delay [Integer]
   #   A time-interval between the each retry (in milliseconds).
   # @option retry_jitter [Integer]
   #   Time-shift range for retry-delay (in milliseconds).
+  # @option instrumenter [#notify]
+  #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+  # @option raise_errors [Boolean]
+  #   Raise errors on library-related limits such as timeout or failed lock obtain.
   # @param [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [Hash<Symbol,Any>]
@@ -80,10 +86,11 @@ class RedisQueuedLocks::Client
     thread_id: RedisQueuedLocks::Resource.get_thread_id,
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
-    timeout: config[:acquire_timeout],
+    timeout: config[:default_timeout],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
+    raise_errors: false,
     &block
   )
     RedisQueuedLocks::Acquier.acquire_lock!(
@@ -97,24 +104,66 @@ class RedisQueuedLocks::Client
       retry_count:,
       retry_delay:,
       retry_jitter:,
+      raise_errors:,
+      instrumenter: config[:instrumenter],
+      &block
+    )
+  end
+
+  # @note See #lock method signature.
+  #
+  # @api public
+  # @since 0.1.0
+  def lock!(
+    lock_name,
+    process_id: RedisQueuedLocks::Resource.get_process_id,
+    thread_id: RedisQueuedLocks::Resource.get_thread_id,
+    ttl: config[:default_lock_ttl],
+    queue_ttl: config[:default_queue_ttl],
+    timeout: config[:default_timeout],
+    retry_count: config[:retry_count],
+    retry_delay: config[:retry_delay],
+    retry_jitter: config[:retry_jitter],
+    &block
+  )
+    lock(
+      lock_name,
+      process_id:,
+      thread_id:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      raise_errors: true,
       &block
     )
   end
 
   # @param lock_name [String] The lock name that should be released.
-  # @return [?]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
   def unlock(lock_name)
-    RedisQueuedLocks::Acquier.release_lock!(redis_client, lock_name)
+    RedisQueuedLocks::Acquier.release_lock!(
+      redis_client,
+      lock_name,
+      config[:instrumenter]
+    )
   end
 
-  # @return [?]
+  # @option batch_size [Integer]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
   def clear_locks(batch_size: config[:lock_release_batch_size])
-    RedisQueuedLocks::Acquier.release_all_locks!(redis_client, batch_size)
+    RedisQueuedLocks::Acquier.release_all_locks!(
+      redis_client,
+      batch_size,
+      config[:instrumenter]
+    )
   end
 end

data/lib/redis_queued_locks/debugger.rb

@@ -10,7 +10,7 @@ module RedisQueuedLocks::Debugger
   # @api private
   # @since 0.1.0
   DEBUG_ENABLED_METHOD = <<~METHOD_DECLARATION.strip.freeze
-    def debug(message) = STDOUT.write_nonblock("#\{message}\n")
+    def debug(message) = STDOUT.write("#\{message}\n")
   METHOD_DECLARATION
 
   # @return [String]

data/lib/redis_queued_locks/instrument/active_support.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+module RedisQueuedLocks::Instrument::ActiveSupport
+  class << self
+    # @param event [String]
+    # @param payload [Hash<String|Symbol,Any>]
+    # @return [void]
+    #
+    # @api private
+    # @since 0.1.0
+    def notify(event, payload = {})
+      ::ActiveSupport::Notifications.instrument(event, payload)
+    end
+  end
+end

data/lib/redis_queued_locks/instrument/void_notifier.rb

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

data/lib/redis_queued_locks/instrument.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+module RedisQueuedLocks::Instrument
+  require_relative 'instrument/void_notifier'
+  require_relative 'instrument/active_support'
+
+  class << self
+    # @param instrumenter [Class,Module,Object]
+    # @return [Boolean]
+    #
+    # @api public
+    # @since 0.1.0
+    def valid_interface?(instrumenter)
+      if instrumenter == RedisQueuedLocks::Instrument::ActiveSupport
+        # NOTE: active_support should be required in your app
+        defined?(::ActiveSupport::Notifications)
+      elsif instrumenter.respond_to?(:notify)
+        # NOTE: the method signature should be (event, payload). Supported variants:
+        #   => [[:req, :event], [:req, :payload]]
+        #   => [[:req, :event], [:opt, :payload]]
+        #   => [[:opt, :event], [:opt, :payload]]
+
+        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
+          # rubocop:disable Layout/MultilineOperationIndentation
+          # NOTE: check the signature vairants
+          f_prm == :req && s_prm == :req ||
+          f_prm == :req && s_prm == :opt ||
+          f_prm == :opt && s_prm == :opt
+          # rubocop:enable Layout/MultilineOperationIndentation
+        else
+          # NOTE: incompatible signature
+          false
+        end
+      else
+        # NOTE: no required method :notify
+        false
+      end
+    end
+  end
+end

data/lib/redis_queued_locks/version.rb

@@ -4,6 +4,6 @@ module RedisQueuedLocks
   # @return [String]
   #
   # @api public
-  # @since 0.0.0
-  VERSION = '0.0.0'
+  # @since 0.0.2
+  VERSION = '0.0.2'
 end

data/lib/redis_queued_locks.rb

@@ -12,7 +12,7 @@ module RedisQueuedLocks
   require_relative 'redis_queued_locks/debugger'
   require_relative 'redis_queued_locks/resource'
   require_relative 'redis_queued_locks/acquier'
-  require_relative 'redis_queued_locks/instrumentation'
+  require_relative 'redis_queued_locks/instrument'
   require_relative 'redis_queued_locks/client'
 
   # @since 0.1.0

data/redis_queued_locks.gemspec

@@ -3,7 +3,7 @@
 require_relative 'lib/redis_queued_locks/version'
 
 Gem::Specification.new do |spec|
-  spec.required_ruby_version = '>= 3.2.0'
+  spec.required_ruby_version = '>= 3.1'
 
   spec.name    = 'redis_queued_locks'
   spec.version = RedisQueuedLocks::VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.2
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-25 00:00:00.000000000 Z
+date: 2024-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -64,7 +64,9 @@ files:
 - lib/redis_queued_locks/debugger.rb
 - lib/redis_queued_locks/debugger/interface.rb
 - lib/redis_queued_locks/errors.rb
-- lib/redis_queued_locks/instrumentation.rb
+- 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/resource.rb
 - lib/redis_queued_locks/version.rb
 - redis_queued_locks.gemspec
@@ -83,14 +85,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.1
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.

data/lib/redis_queued_locks/instrumentation.rb

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-# @api private
-# @since 0.1.0
-module RedisQueuedLocks::Instrumentation
-end