redis_queued_locks 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b175564df436902d56e07a376f0257118eced8d7c81dbb81837e63cdef74938
-  data.tar.gz: f88d3e83045cb4dd4dcd10b12744399ce45d3b99a84f6ca492d801a678db55f0
+  metadata.gz: 6b1c8d60f41d2dc4f3eda798efa02a4764b877e6666e8babd7cf1a7827a4b288
+  data.tar.gz: 983e142251b344055013aa2aac2965ad542d44f5c8f81ac410f97cdef7b216b3
 SHA512:
-  metadata.gz: ae486564a408bc9039d6b09f3fe08ba37e733bae902ec2c3f55eae84b22a05e6c6f31bc9ceafc5ee78a10ae34dfdc0b3e7dcbfb09a41f74795ed29dce823a6bc
-  data.tar.gz: ba40ab572fb1863b0bcddee6536385d19e3b3c7c9df07b2e2d71d74ad740eccb05a18847222be70bf6796596ce2b93266dbf462dccab294c6200a4441ca1f1a7
+  metadata.gz: 88b91754923e546767d03999601fb98bd04b00fb426e50691e2fd4ce1bf13e345c19179b534660a639d0a885d1fdad4db94ffda0fa4383d7d9dcf53981ca481b
+  data.tar.gz: f9368018c66eee962a9dd6be1b38efe7bb4359cdfb262956f4e2e43622aaf747b67b4aa6b7a9bcda6c8449e011cb1c2954d5a6e5324afdbfbb8eea0ca96085b0

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [1.2.0] - 2024-04-27
+### Added
+- Documentation updates;
+- Logging: support for `semantic_logger` loggers (see: https://logger.rocketjob.io/) (https://github.com/reidmorrison/semantic_logger)
+
 ## [1.1.0] - 2024-04-01
 ### Added
 - Documentation updates:
@@ -7,8 +12,7 @@
   - added missing docs for `config.dead_request_ttl`;
   - some minor updates;
 ### Changed
-- `#clear_dead_requests`: `:scan_size` is equal to `config[:lock_release_batch_size]` now (instead of to `config[:key_extraction_batch_size]`);
-  cuz `#clear_dead_requests` works with lock releasing;
+- `#clear_dead_requests`: `:scan_size` is equal to `config[:lock_release_batch_size]` now (instead of to `config[:key_extraction_batch_size]`), cuz `#clear_dead_requests` works with lock releasing;
 
 ## [1.0.0] - 2024-04-01
 - First Major Release;
@@ -195,7 +199,7 @@
 ### Changed
 - The lock acquier identifier (`acq_id`) now includes the fiber id, the ractor id and an unique per-process
   10 byte string. It is added in order to prevent collisions between different processes/pods
-  that will have the same procjet id / thread id identifiers (cuz it is an object_id integers) that can lead
+  that will have the same process id / thread id identifiers (cuz it is an object_id integers) that can lead
   to the same position with the same `acq_id` for different processes/pods in the lock request queue.
 
 ## [0.0.8] - 2024-02-27

data/README.md

@@ -150,8 +150,8 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   config.is_timed_by_default = false
 
   # (default: 100)
-  # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic (uses SCAN);
-  # - affects the performancs of your Redis and Ruby Application (configure thoughtfully);
+  # - how many items will be released at a time in #clear_locks and in #clear_dead_requests (uses SCAN);
+  # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
   config.lock_release_batch_size = 100
 
   # (default: 500)
@@ -324,10 +324,12 @@ def lock(
   - should be logged the each try of lock acquiring (a lot of logs can be generated depending on your retry configurations);
   - pre-configured in `config[:log_lock_try]`;
   - `false` by default;
-- `block` - `[Block]`
+- `block` - (optional) `[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);
   - If block is **not passed** the obtained lock will be released after it's ttl;
+  - If you want the block to have a TTL too and this TTL to be the same as TTL of the lock
+    use `timed: true` option (`rql.lock("my_lock", timed: true, ttl: 5_000) { ... }`)
 
 Return value:
 
@@ -453,6 +455,43 @@ rql.lock_info("my_lock")
 }
 ```
 
+- (`:queue_ttl`) setting a short limit of time to the lock request queue position (if a process fails to acquire
+  the lock within this period of time (and before timeout/retry_count limits occurs of course) -
+  it's lock request will be moved to the end of queue):
+
+```ruby
+rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
+# "queue_ttl: 5": 5 seconds time slot before the lock request moves to the end of queue;
+# "timeout" and "retry_count" is used as "endless lock try attempts" example to show the lock queue behavior;
+
+# lock queue: =>
+[
+ "rql:acq:123/456/567/676/374dd74324", 
+ "rql:acq:123/456/567/677/374dd74322", # <- long living lock
+ "rql:acq:123/456/567/679/374dd74321",
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+]
+
+# ... some period of time (2 seconds later)
+# lock queue: =>
+[
+ "rql:acq:123/456/567/677/374dd74322", # <- long living lock
+ "rql:acq:123/456/567/679/374dd74321",
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+]
+
+# ... some period of time (3 seconds later)
+# ... queue_ttl time limit is reached
+# lock queue: =>
+[
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here (moved to the end of the queue)
+]
+
+```
+
 ---
 
 #### #lock! - exceptional lock obtaining
@@ -563,9 +602,9 @@ rql.queue_info("your_lock_name")
 {
   "lock_queue" => "rql:lock_queue:your_lock_name",
   "queue" => [
-    { "acq_id" => "rql:acq:123/456/567/678/fa76df9cc2", "score" => 1},
-    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 2},
-    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 3},
+    { "acq_id" => "rql:acq:123/456/567/678/fa76df9cc2", "score" => 1711606640.540842},
+    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 1711606640.540906},
+    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 1711606640.540963},
     # ...etc
   ]
 }
@@ -587,6 +626,8 @@ rql.locked?("your_lock_name") # => true/false
 
 #### #queued?
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - is the lock queued for obtain / has requests for obtain?
 
 ```ruby
@@ -635,7 +676,7 @@ rql.unlock("your_lock_name")
   result: {
     rel_time: 0.02, # time spent to lock release (in seconds)
     rel_key: "rql:lock:your_lock_name", # released lock key
-    rel_queue: "rql:lock_queue:your_lock_name" # released lock key queue
+    rel_queue: "rql:lock_queue:your_lock_name", # released lock key queue
     queue_res: :released, # or :nothing_to_release
     lock_res: :released # or :nothing_to_release
   }
@@ -662,12 +703,11 @@ rql.unlock("your_lock_name")
     - pre-configured value in `config[:isntrumenter]`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
-
 - returns:
- - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
- - result data:
-  - `:rel_time` - `Numeric` - time spent to release all locks and related queus;
-  - `:rel_key_cnt` - `Integer` - the number of released Redis keys (queues+locks);
+  - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
+  - result data:
+    - `:rel_time` - `Numeric` - time spent to release all locks and related queus;
+    - `:rel_key_cnt` - `Integer` - the number of released Redis keys (queues+locks);
 
 ```ruby
 rql.clear_locks
@@ -699,13 +739,14 @@ rql.clear_locks
     - custom logger object;
     - pre-configured in `config[:logger]`;
 - 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
+- returns `{ ok: false, result: :async_expire_or_no_lock }` when a lock not found or a lock is already 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";
+  - the method uses Redis'es **CAS** (check-and-set) behavior;
   - what can happen during these steps:
     - lock is expired between commands or before the first command;
     - lock is expired before the second command;
@@ -908,7 +949,7 @@ Accepts:
   - has a preconfigured value in `config[:dead_request_ttl]` (1 day by default);
 - `:sacn_size` - (optional) `[Integer]`
   - the batch of scanned keys for Redis'es SCAN command;
-  - has a preconfigured valie in `config[:key_extraction_batch_size]`;
+  - has a preconfigured valie in `config[:lock_release_batch_size]`;
 - `:logger` - (optional) `[::Logger,#debug]`
   - custom logger object;
   - pre-configured in `config[:logger]`;
@@ -994,7 +1035,7 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 ### Instrumentation Events
 
-<sup>\[[back to top](#instrumentation-events)\]</sup>
+<sup>\[[back to top](#instrumentation)\]</sup>
 
 List of instrumentation events
 
@@ -1052,6 +1093,7 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **strict redlock algorithm support** (support for many `RedisClient` instances);
+- deadlock detection (with some options for auto-resolving);
 - Semantic Error objects for unexpected Redis errors;
 - better specs with 100% test coverage (total rework);
 - (non-`timed` locks): per-ruby-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
@@ -1059,6 +1101,7 @@ Detalized event semantics and payload structure:
   whose ttl may expire before the block execution completes). It makes sense for non-`timed` locks *only*;
 - lock request prioritization;
 - support for LIFO strategy;
+- support for Random Access strategy;
 - more structured logging (separated docs);
 - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
 - better code stylization (+ some refactorings);

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::AcquireLock::DelayExecution
   # Sleep with random time-shifting (it is necessary for empty lock-acquirement time slots).
   #
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::DelayExecution
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def delay_execution(retry_delay, retry_jitter)
     delay = (retry_delay + rand(retry_jitter)).to_f / 1_000
     sleep(delay)

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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 # rubocop:disable Metrics/ModuleLength, Metrics/BlockNesting
 module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   # @param redis [RedisClient]
@@ -21,7 +21,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
@@ -259,7 +259,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   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)
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
   # @param timeout [NilClass,Integer]
   #   Time period after which the logic will fail with timeout error.
@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
   # @return [Any]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
     ::Timeout.timeout(timeout, &block)
   rescue ::Timeout::Error

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   # @param redis [RedisClient] Redis connection manager.
@@ -18,7 +18,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   # @return [Any,NilClass] nil is returned no block parametr is provided.
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def yield_with_expire(
     redis,
     logger,
@@ -59,7 +59,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   # @return [Any]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def yield_with_timeout(timeout, lock_key, lock_ttl, &block)
     ::Timeout.timeout(timeout, &block)
   rescue ::Timeout::Error

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
@@ -12,21 +12,21 @@ module RedisQueuedLocks::Acquier::AcquireLock
   require_relative 'acquire_lock/yield_with_expire'
   require_relative 'acquire_lock/try_to_lock'
 
-  # @since 0.1.0
+  # @since 1.0.0
   extend TryToLock
-  # @since 0.1.0
+  # @since 1.0.0
   extend DelayExecution
-  # @since 0.1.0
+  # @since 1.0.0
   extend YieldWithExpire
-  # @since 0.1.0
+  # @since 1.0.0
   extend WithAcqTimeout
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   # @return [Integer] Redis time error (in milliseconds).
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   REDIS_TIMESHIFT_ERROR = 2
 
   class << self
@@ -87,7 +87,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #  - If block is given the result of block's yeld will be returned.
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def acquire_lock(
       redis,
       lock_name,

data/lib/redis_queued_locks/acquier/clear_dead_requests.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ClearDeadRequests
   class << self
     # @param redis_client [RedisClient]
@@ -13,7 +13,7 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
     # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def clear_dead_requests(redis_client, scan_size, dead_ttl, logger, instrumenter, instrument)
       dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1000.0)
 
@@ -39,7 +39,7 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
     # @return [Enumerator]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def each_lock_queue(redis_client, scan_size, &block)
       redis_client.scan(
         'MATCH',

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ExtendLockTTL
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.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);
@@ -20,7 +20,7 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @return [Hash<Symbol,Boolean|Symbol>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 

data/lib/redis_queued_locks/acquier/is_locked.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::IsLocked
   class << self
     # @param redis_client [RedisClient]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Acquier::IsLocked
     # @return [Boolean]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def locked?(redis_client, lock_name)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       redis_client.call('EXISTS', lock_key) == 1

data/lib/redis_queued_locks/acquier/is_queued.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::IsQueued
   class << self
     # @param redis_client [RedisClient]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Acquier::IsQueued
     # @return [Boolean]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def queued?(redis_client, lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
       redis_client.call('EXISTS', lock_key_queue) == 1

data/lib/redis_queued_locks/acquier/keys.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::Keys
   class << self
     # @param redis_client [RedisClient]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Acquier::Keys
     # @return [Array<String>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def keys(redis_client, scan_size:)
       Set.new.tap do |keys|
         redis_client.scan(

data/lib/redis_queued_locks/acquier/lock_info.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::LockInfo
   class << self
     # @param redis_client [RedisClient]
@@ -17,7 +17,7 @@ module RedisQueuedLocks::Acquier::LockInfo
     #   }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def lock_info(redis_client, lock_name)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 

data/lib/redis_queued_locks/acquier/locks.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::Locks
   class << self
     # @param redis_client [RedisClient]
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::Locks
     # @return [Set<String>,Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def locks(redis_client, scan_size:, with_info:)
       redis_client.with do |rconn|
         lock_keys = scan_locks(rconn, scan_size)
@@ -25,7 +25,7 @@ module RedisQueuedLocks::Acquier::Locks
     # @return [Set<String>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def scan_locks(redis_client, scan_size)
       Set.new.tap do |lock_keys|
         redis_client.scan(
@@ -44,7 +44,7 @@ module RedisQueuedLocks::Acquier::Locks
     # @return [Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     # rubocop:disable Metrics/MethodLength
     def extract_locks_info(redis_client, lock_keys)
       # TODO: refactor with RedisQueuedLocks::Acquier::LockInfo

data/lib/redis_queued_locks/acquier/queue_info.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::QueueInfo
   class << self
     # Returns an information about the required lock queue by the lock name. The result
@@ -23,7 +23,7 @@ module RedisQueuedLocks::Acquier::QueueInfo
     #   }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def queue_info(redis_client, lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
 

data/lib/redis_queued_locks/acquier/queues.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::Queues
   class << self
     # @param redis_client [RedisClient]
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<String>,Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def queues(redis_client, scan_size:, with_info:)
       redis_client.with do |rconn|
         lock_queues = scan_queues(rconn, scan_size)
@@ -25,7 +25,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<String>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def scan_queues(redis_client, scan_size)
       Set.new.tap do |lock_queues|
         redis_client.scan(
@@ -44,7 +44,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def extract_queues_info(redis_client, lock_queues)
       # TODO: refactor with RedisQueuedLocks::Acquier::QueueInfo
       Set.new.tap do |seeded_queues|

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ReleaseAllLocks
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   class << self
@@ -27,7 +27,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   Format: { ok: true, result: Hash<Symbol,Numeric> }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def release_all_locks(redis, batch_size, logger, instrumenter, instrument)
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
@@ -59,7 +59,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   - Exmaple: { ok: true, result: { rel_key_cnt: 12345 } }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def fully_release_all_locks(redis, batch_size)
       result = redis.with do |rconn|
         rconn.pipelined do |pipeline|

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ReleaseLock
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   class << self
@@ -27,7 +27,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     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)
@@ -76,7 +76,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def fully_release_lock(redis, lock_key, lock_key_queue)
       result = redis.with do |rconn|
         rconn.multi do |transact|

data/lib/redis_queued_locks/acquier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier
   require_relative 'acquier/acquire_lock'
   require_relative 'acquier/release_lock'

data/lib/redis_queued_locks/client.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
-  # @since 0.1.0
+  # @since 1.0.0
   include Qonfig::Configurable
 
   configuration do
@@ -41,7 +41,7 @@ class RedisQueuedLocks::Client
   # @return [RedisClient]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   attr_reader :redis_client
 
   # NOTE: attr_access here is chosen intentionally in order to have an ability to change
@@ -49,7 +49,7 @@ class RedisQueuedLocks::Client
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   attr_accessor :uniq_identity
 
   # @param redis_client [RedisClient]
@@ -60,7 +60,7 @@ class RedisQueuedLocks::Client
   # @return [void]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def initialize(redis_client, &configs)
     configure(&configs)
     @uniq_identity = config[:uniq_identifier].call
@@ -116,7 +116,7 @@ class RedisQueuedLocks::Client
   #   - If block is given the result of block's yeld will be returned.
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def lock(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -164,7 +164,7 @@ class RedisQueuedLocks::Client
   # @note See #lock method signature.
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def lock!(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -219,7 +219,7 @@ class RedisQueuedLocks::Client
   #   }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def unlock(
     lock_name,
     logger: config[:logger],
@@ -238,7 +238,7 @@ class RedisQueuedLocks::Client
   # @return [Boolean]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locked?(lock_name)
     RedisQueuedLocks::Acquier::IsLocked.locked?(redis_client, lock_name)
   end
@@ -247,7 +247,7 @@ class RedisQueuedLocks::Client
   # @return [Boolean]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queued?(lock_name)
     RedisQueuedLocks::Acquier::IsQueued.queued?(redis_client, lock_name)
   end
@@ -256,7 +256,7 @@ class RedisQueuedLocks::Client
   # @return [Hash<String,String|Numeric>,NilClass]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def lock_info(lock_name)
     RedisQueuedLocks::Acquier::LockInfo.lock_info(redis_client, lock_name)
   end
@@ -265,7 +265,7 @@ class RedisQueuedLocks::Client
   # @return [Hash<String|Array<Hash<String,String|Numeric>>,NilClass]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queue_info(lock_name)
     RedisQueuedLocks::Acquier::QueueInfo.queue_info(redis_client, lock_name)
   end
@@ -288,7 +288,7 @@ class RedisQueuedLocks::Client
   #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
@@ -311,7 +311,7 @@ class RedisQueuedLocks::Client
   #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def clear_locks(
     batch_size: config[:lock_release_batch_size],
     logger: config[:logger],
@@ -345,7 +345,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>,Set<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locks(scan_size: config[:key_extraction_batch_size], with_info: false)
     RedisQueuedLocks::Acquier::Locks.locks(redis_client, scan_size:, with_info:)
   end
@@ -356,7 +356,7 @@ class RedisQueuedLocks::Client
   # @return [Set<Hash<String,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locks_info(scan_size: config[:key_extraction_batch_size])
     locks(scan_size:, with_info: true)
   end
@@ -376,7 +376,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>,String<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queues(scan_size: config[:key_extraction_batch_size], with_info: false)
     RedisQueuedLocks::Acquier::Queues.queues(redis_client, scan_size:, with_info:)
   end
@@ -387,7 +387,7 @@ class RedisQueuedLocks::Client
   # @return [Set<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queues_info(scan_size: config[:key_extraction_batch_size])
     queues(scan_size:, with_info: true)
   end
@@ -396,7 +396,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def keys(scan_size: config[:key_extraction_batch_size])
     RedisQueuedLocks::Acquier::Keys.keys(redis_client, scan_size:)
   end
@@ -415,7 +415,8 @@ class RedisQueuedLocks::Client
   #   Format: { ok: true, result: { processed_queus: Set<String> } }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.1.0
   def clear_dead_requests(
     dead_ttl: config[:dead_request_ttl],
     scan_size: config[:lock_release_batch_size],

data/lib/redis_queued_locks/debugger/interface.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Debugger::Interface
   # @param message [String]
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def debug(message)
     RedisQueuedLocks::Debugger.debug(message)
   end
@@ -15,7 +15,7 @@ module RedisQueuedLocks::Debugger::Interface
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def enable_debugger!
     RedisQueuedLocks::Debugger.enable!
   end
@@ -23,7 +23,7 @@ module RedisQueuedLocks::Debugger::Interface
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def disable_debugger!
     RedisQueuedLocks::Debugger.disable!
   end

data/lib/redis_queued_locks/debugger.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Debugger
   require_relative 'debugger/interface'
 
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   DEBUG_ENABLED_METHOD = <<~METHOD_DECLARATION.strip.freeze
     def debug(message) = STDOUT.write("#\{message}\n")
   METHOD_DECLARATION
@@ -16,20 +16,20 @@ module RedisQueuedLocks::Debugger
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   DEBUG_DISABLED_MEHTOD = <<~METHOD_DECLARATION.strip.freeze
     def debug(message); end
   METHOD_DECLARATION
 
   class << self
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     instance_variable_set(:@enabled, false)
 
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def enable!
       @enabled = true
       eval(DEBUG_ENABLED_METHOD)
@@ -38,7 +38,7 @@ module RedisQueuedLocks::Debugger
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def disable!
       @enabled = false
       eval(DEBUG_DISABLED_MEHTOD)
@@ -47,7 +47,7 @@ module RedisQueuedLocks::Debugger
     # @return [Boolean]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def enabled?
       @enabled
     end
@@ -56,7 +56,7 @@ module RedisQueuedLocks::Debugger
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def debug(message); end
   end
 end

data/lib/redis_queued_locks/errors.rb

@@ -2,26 +2,26 @@
 
 module RedisQueuedLocks
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   Error = Class.new(::StandardError)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   ArgumentError = Class.new(::ArgumentError)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAlreadyObtainedError = Class.new(Error)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAcquiermentTimeoutError = Class.new(Error)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAcquiermentRetryLimitError = Class.new(Error)
 
   # @api pulic
-  # @since 0.1.0
+  # @since 1.0.0
   TimedLockTimeoutError = Class.new(Error)
 end

data/lib/redis_queued_locks/instrument/active_support.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument::ActiveSupport
   class << self
     # @param event [String]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Instrument::ActiveSupport
     # @return [void]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def notify(event, payload = {})
       ::ActiveSupport::Notifications.instrument(event, payload)
     end

data/lib/redis_queued_locks/instrument/void_notifier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument::VoidNotifier
   class << self
     # @param event [String]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Instrument::VoidNotifier
     # @return [void]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def notify(event, payload = {}); end
   end
 end

data/lib/redis_queued_locks/instrument.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument
   require_relative 'instrument/void_notifier'
   require_relative 'instrument/active_support'
@@ -11,7 +11,7 @@ module RedisQueuedLocks::Instrument
     # @return [Boolean]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def valid_interface?(instrumenter)
       if instrumenter == RedisQueuedLocks::Instrument::ActiveSupport
         # NOTE: active_support should be required in your app

data/lib/redis_queued_locks/logging/void_logger.rb

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

data/lib/redis_queued_locks/logging.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
 
   class << self
-    # @param logger [::Logger,#debug]
+    # @param logger [::Logger,#debug,::SemanticLogger::Logger]
     # @return [Boolean]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
+    # @version 1.2.0
     def valid_interface?(logger)
       return true if logger.is_a?(::Logger)
 
+      # NOTE:
+      #   - convinient/conventional way to support the popular`semantic_logger` library
+      #   - see https://logger.rocketjob.io/
+      #   - see https://github.com/reidmorrison/semantic_logger
+      return true if defined?(::SemanticLogger::Logger) && logger.is_a?(::SemanticLogger::Logger)
+
       # NOTE: should provide `#debug` method.
       return false unless logger.respond_to?(:debug)
 

data/lib/redis_queued_locks/resource.rb

@@ -1,24 +1,24 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Resource
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   KEY_PATTERN = 'rql:lock*'
 
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   LOCK_PATTERN = 'rql:lock:*'
 
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   LOCK_QUEUE_PATTERN = 'rql:lock_queue:*'
 
   class << self
@@ -29,7 +29,7 @@ module RedisQueuedLocks::Resource
     # @return [String]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def calc_uniq_identity
       SecureRandom.hex(8)
     end
@@ -42,7 +42,7 @@ module RedisQueuedLocks::Resource
     # @return [String]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def acquier_identifier(process_id, thread_id, fiber_id, ractor_id, identity)
       "rql:acq:#{process_id}/#{thread_id}/#{fiber_id}/#{ractor_id}/#{identity}"
     end
@@ -51,7 +51,7 @@ module RedisQueuedLocks::Resource
     # @return [String]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def prepare_lock_key(lock_name)
       "rql:lock:#{lock_name}"
     end
@@ -60,7 +60,7 @@ module RedisQueuedLocks::Resource
     # @return [String]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def prepare_lock_queue(lock_name)
       "rql:lock_queue:#{lock_name}"
     end
@@ -68,7 +68,7 @@ module RedisQueuedLocks::Resource
     # @return [Float] Redis's <Set> score that is calculated from the time (epoch) as a float.
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def calc_initial_acquier_position
       Time.now.to_f
     end
@@ -77,7 +77,7 @@ module RedisQueuedLocks::Resource
     # @return [Float] Redis's <Set> score barrier for acquiers that should be removed from queue.
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def acquier_dead_score(queue_ttl)
       Time.now.to_f - queue_ttl
     end
@@ -91,7 +91,7 @@ module RedisQueuedLocks::Resource
     #   Is the lock request time limit has reached or not.
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def dead_score_reached?(acquier_position, queue_ttl)
       (acquier_position + queue_ttl) < Time.now.to_f
     end
@@ -100,7 +100,7 @@ module RedisQueuedLocks::Resource
     # @return [String]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def lock_key_from_queue(lock_queue)
       # NOTE: 15 is a start position of the lock name
       "rql:lock:#{lock_queue[15..]}"
@@ -109,7 +109,7 @@ module RedisQueuedLocks::Resource
     # @return [Integer]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def get_thread_id
       ::Thread.current.object_id
     end
@@ -117,7 +117,7 @@ module RedisQueuedLocks::Resource
     # @return [Integer]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def get_fiber_id
       ::Fiber.current.object_id
     end
@@ -125,7 +125,7 @@ module RedisQueuedLocks::Resource
     # @return [Integer]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def get_ractor_id
       ::Ractor.current.object_id
     end
@@ -133,7 +133,7 @@ module RedisQueuedLocks::Resource
     # @return [Integer]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def get_process_id
       ::Process.pid
     end

data/lib/redis_queued_locks/utilities.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Utilities
   module_function
 
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Utilities
   # @return [Any]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def run_non_critical(&block)
     yield rescue nil
   end

data/lib/redis_queued_locks/version.rb

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

data/lib/redis_queued_locks.rb

@@ -7,7 +7,7 @@ require 'securerandom'
 require 'logger'
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks
   require_relative 'redis_queued_locks/version'
   require_relative 'redis_queued_locks/errors'
@@ -20,6 +20,6 @@ module RedisQueuedLocks
   require_relative 'redis_queued_locks/instrument'
   require_relative 'redis_queued_locks/client'
 
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Debugger::Interface
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-02 00:00:00.000000000 Z
+date: 2024-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client