redis_queued_locks 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f787fbfe22ef8fe8dec78e5b17d4305621a4b9e2df7d3582648959e68dabef09
-  data.tar.gz: 8d874d80738959f41985e6e52d6668aa63d8232ca4964006be82f5d67ea7e1a6
+  metadata.gz: a2028a137ac36d716a0f9728656f536c373d21691fe64bf5fa1970db160fbe51
+  data.tar.gz: 3d065601fac650cf7d2a8fcb63745ffbf91ecd2cc553d936c693b2e45fee752f
 SHA512:
-  metadata.gz: eb726c270398079b142d68e3e45dd93226e1f17b52f370107db2f4cc47bfa6b0ce010f55dec029443bfb932d73f905f61040087577f47dca9cef5ad505fca430
-  data.tar.gz: 129089ba8f764ecabae8d0598af0f627a1156bb8b1a3e845697f1f32863d7ccd3eb2cd64cb80406408e8518b9809b35cce36e1253598744d52529d32cb092598
+  metadata.gz: e7d6698032bab56ebb0cc85abf3b13bcffe499c019708b845962bb626ac0e27d3da35c27462816c3c37d664117ba3c6a8c916dca231fb9fffdb862695cf2c261
+  data.tar.gz: 7b139c4bff4587783dc0df0f67bc7b985569ff5590aaaa8cb4370cdf2d3f9f9954bf9c99ade1a60e47e48ac4c450b58c308dce32ab10e0e1b5a40d6003ed5019

data/.ruby-version

@@ -1 +1 @@
-3.3.3
+3.3.4

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [1.10.0] - 2024-08-11
+### Changed
+- Timed invocations (`"timeed blocks of code"` / `timed: true`):
+  - the way of timeout error interception has been changed:
+    - instead of the `rescue Timeout::Error` around the block of code the timeout interception
+      now uses `Timeout#timeout`'s custom exception class/message replacement API;
+    - `rescue Timeout::Error` can lead to incorrect exception interception: intercept block's-related
+      Timeout::Error that is not RQL-related error;
+### Added
+- `RedisQueuedLocks::Swarm`: missing YARDocs;
+- Separated `Logging Configuration` readme section (that is placed inside the main configuration section already);
+- Separated `Instrumentation Configuration` readme section (that is placed inside the main configuration section already);
+### Removed
+- `RedisQueudLocks::Swarm`: some useless YARDocs;
+
 ## [1.9.0] - 2024-07-15
 ### Added
 - Brand New Extremely Major Feature: **Swarm Mode** - eliminate zombie locks with a swarm:

data/README.md

@@ -54,9 +54,11 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 - [Lock Access Strategies](#lock-access-strategies)
   - [queued](#lock-access-strategies)
   - [random](#lock-access-strategies)
-- [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks)
+- [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks)
 - [Logging](#logging)
+  - [Logging Configuration](#logging-configuration)
 - [Instrumentation](#instrumentation)
+  - [Instrumentation Configuration](#instrumentation-configuration)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
@@ -467,7 +469,7 @@ def lock(
     - `:extendable_work_through` - continue working under the lock **with** lock's TTL extension;
     - `:wait_for_lock` - (default) - work in classic way (with timeouts, retry delays, retry limits, etc - in classic way :));
     - `:dead_locking` - fail with deadlock exception;
-  - See [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) documentation section for details;
+  - See [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) documentation section for details;
 - `identity` - (optional) `[String]`
   - An unique string that is unique per `RedisQueuedLock::Client` instance. Resolves the
     collisions between the same process_id/thread_id/fiber_id/ractor_id identifiers on different
@@ -586,7 +588,7 @@ Return value:
     - `:extendable_conflict_work_through` - reentrant lock acquiring process with lock's TTL extension. Suitable for `conflict_strategy: :extendable_work_through`;
     - `:conflict_work_through` - reentrant lock acquiring process without lock's TTL extension. Suitable for `conflict_strategy: :work_through`;
     - `:dead_locking` - current process tries to acquire a lock that is already acquired by them. Suitalbe for `conflict_startegy: :dead_locking`;
-    - For more details see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) readme section;
+    - For more details see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) readme section;
   - For successful lock obtaining:
     ```ruby
     {
@@ -786,7 +788,7 @@ rql.lock('my_lock', retry_delay: 3000, ttl: 3000, access_strategy: :random)
   - (`RedisQueuedLocks::LockAlreadyObtainedError`) when `fail_fast` is `true` and lock is already obtained;
   - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
   - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
-  - (`RedisQueuedLocks::ConflictLockObtainError`) when `conflict_strategy: :dead_locking` is used and the "same-process-dead-lock" is happened (see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) for details);
+  - (`RedisQueuedLocks::ConflictLockObtainError`) when `conflict_strategy: :dead_locking` is used and the "same-process-dead-lock" is happened (see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) for details);
 
 ```ruby
 def lock!(
@@ -1479,7 +1481,7 @@ rql.current_acquirer_id
 <sup>\[[back to top](#usage)\]</sup>
 
 - get a current host identifier in RQL notation that you can use for debugging purposes during the lock analyzis;
-- the host is a ruby worker (a combination of process/thread/ractor) that is alive and can obtain locks;
+- the host is a ruby worker (a combination of process/thread/ractor/identity) that is alive and can obtain locks;
 - the host is limited to `process`/`thread`/`ractor` (without `fiber`) combination cuz we have no abilities to extract
   all fiber objects from the current ruby process when at least one ractor object is defined (**ObjectSpace** loses
   abilities to extract `Fiber` and `Thread` objects after the any ractor is created) (`Thread` objects are analyzed
@@ -1559,7 +1561,7 @@ rql.possible_host_ids
 
 > Eliminate zombie locks with a swarm.
 
-**This documentation section is in progress!**
+**This documentation section is in progress!** (see the changelog and the usage preview for details at this moment)
 
 [(work and usage preview (temporary example-based docs))](#work-and-usage-preview-temporary-example-based-docs)
 
@@ -1615,6 +1617,7 @@ rql.possible_host_ids
     config.swarm.flush_zombies.redis_config.pooled = false # NOTE: individual redis config
     config.swarm.flush_zombies.redis_config.config = {} # NOTE: individual redis config
     config.swarm.flush_zombies.redis_config.pool_config = {} # NOTE: individual redis config
+  end
   ```
 </details>
 
@@ -1763,7 +1766,7 @@ rql.possible_host_ids
 
 ---
 
-## Dead locks and Reentrant locks
+## Deadlocks and Reentrant locks
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
@@ -1785,6 +1788,9 @@ rql.possible_host_ids
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
+- [Logging Configuration](#logging-configuration)
+
+
 - default logs (raised from `#lock`/`#lock!`):
 
 ```ruby
@@ -1820,14 +1826,87 @@ rql.possible_host_ids
 
 ---
 
+### Logging Configuration
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+**NOTICE**: logging can be sampled via:
+- `config.log_samplign_enabled = true` (**false** by default);
+- `config.log_sampler = RedisQueuedLocks::Logging::Sampler` (used by default);
+- see **RedisQueuedLocks::Logging::Sampler** implementation in source code for customization details;
+
+```ruby
+# (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;
+# - supports `SemanticLogger::Logger` (see "semantic_logger" gem)
+# - at this moment the only debug logs are realised in following cases:
+#   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+# - by default uses VoidLogger that does nothing;
+config.logger = RedisQueuedLocks::Logging::VoidLogger
+
+# (default: false)
+# - adds additional debug logs;
+# - enables additional logs for each internal try-retry lock acquiring (a lot of logs can be generated depending on your retry configurations);
+# - it adds following debug logs in addition to the existing:
+#   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status");
+#   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status", "last_ext_ttl", "last_ext_ts");
+#   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status", last_spc_ts);
+#   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat")";
+#   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue");
+#   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue", "<current_lock_data>");
+#   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+#   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+config.log_lock_try = false
+
+# (default: false)
+# - enables <log sampling>: only the configured percent of RQL cases will be logged;
+# - disabled by default;
+# - works in tandem with <config.log_sampling_percent> and <log.sampler> configs;
+config.log_sampling_enabled = false
+
+# (default: 15)
+# - the percent of cases that should be logged;
+# - take an effect when <config.log_sampling_enalbed> is true;
+# - works in tandem with <config.log_sampling_enabled> and <config.log_sampler> configs;
+config.log_sampling_percent = 15
+
+# (default: RedisQueuedLocks::Logging::Sampler)
+# - percent-based log sampler that decides should be RQL case logged or not;
+# - works in tandem with <config.log_sampling_enabled> and <config.log_sampling_percent> configs;
+# - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+#   method so the algorithm error is ~(0%..13%);
+# - you can provide your own log sampler with bettter algorithm that should realize
+#   `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Logging::Sampler` for example);
+config.log_sampler = RedisQueuedLocks::Logging::Sampler
+```
+
+---
+
 ## Instrumentation
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - [Instrumentation Events](#instrumentation-events)
+- [Instrumentation Configuration](#instrumentation-configuration)
 
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
 
+Instrumentation can be sampled. See [Instrumentation Configuration](#instrumentation-configuration) section for details.
+
 Instrumenter object should provide `notify(event, payload)` method with the following signarue:
 
 - `event` - `string`;
@@ -1843,6 +1922,48 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 ---
 
+### Instrumentation Configuration
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+**NOTICE**: instrumentation can be sampled via:
+- `config.instr_sampling_enabled = true` (**false** by default);
+- `config.instr_sampler = RedisQueuedLocks::Instrument::Sampler` (used by default);
+- see **RedisQueuedLocks::Instrument::Sampler** implementation in source code for customization details;
+
+```ruby
+# (default: RedisQueuedLocks::Instrument::VoidNotifier)
+# - instrumentation layer;
+# - you can provide your own instrumenter that should realize `#notify(event, payload = {})` interface:
+#   - event: <string> requried;
+#   - payload: <hash> requried;
+# - disabled by default via `VoidNotifier`;
+config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
+
+# (default: false)
+# - enables <instrumentaion sampling>: only the configured percent of RQL cases will be instrumented;
+# - disabled by default;
+# - works in tandem with <config.instr_sampling_percent and <log.instr_sampler>;
+config.instr_sampling_enabled = false
+
+# (default: 15)
+# - the percent of cases that should be instrumented;
+# - take an effect when <config.instr_sampling_enalbed> is true;
+# - works in tandem with <config.instr_sampling_enabled> and <config.instr_sampler> configs;
+config.instr_sampling_percent = 15
+
+# (default: RedisQueuedLocks::Instrument::Sampler)
+# - percent-based log sampler that decides should be RQL case instrumented or not;
+# - works in tandem with <config.instr_sampling_enabled> and <config.instr_sampling_percent> configs;
+# - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+#   method so the algorithm error is ~(0%..13%);
+# - you can provide your own log sampler with bettter algorithm that should realize
+#   `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Instrument::Sampler` for example);
+config.instr_sampler = RedisQueuedLocks::Instrument::Sampler
+```
+
+---
+
 ### Instrumentation Events
 
 <sup>\[[back to top](#instrumentation)\]</sup>

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

@@ -109,18 +109,26 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.9.0
+  # @version 1.10.0
   def yield_with_timeout(timeout, lock_key, lock_ttl, acquier_id, host_id, meta, &block)
-    ::Timeout.timeout(timeout, &block)
-  rescue ::Timeout::Error
-    raise(
+    ::Timeout.timeout(
+      timeout,
       RedisQueuedLocks::TimedLockTimeoutError,
+      # NOTE:
+      #   - this string is generated on each invocation cuz we need to raise custom exception
+      #     from the Timeout API in order to prevent incorred Timeout::Error interception when
+      #     the intercepted error is caused from the block not from the RQL;
+      #   - we can't omit this string object creation at the moment via original Ruby's Timeout API;
+      # TODO:
+      #   - refine Timeout#timeout (via Ruby's Refinement API) in order to provide lazy exception
+      #     message initialization;
       "Passed <timed> block of code exceeded the lock TTL " \
       "(lock: \"#{lock_key}\", " \
       "ttl: #{lock_ttl}, " \
       "meta: #{meta ? meta.inspect : '<no-meta>'}, " \
       "acq_id: \"#{acquier_id}\", " \
-      "hst_id: \"#{host_id}\")"
+      "hst_id: \"#{host_id}\")",
+      &block
     )
   end
 end

data/lib/redis_queued_locks/swarm.rb

@@ -130,6 +130,8 @@ class RedisQueuedLocks::Swarm
     )
   end
 
+  # @option zombie_ttl [Integer]
+  # @option lock_scan_size [Integer]
   # @return [Set<String>]
   #
   # @api public
@@ -145,6 +147,8 @@ class RedisQueuedLocks::Swarm
     )
   end
 
+  # @option zombie_ttl [Integer]
+  # @option lock_scan_size [Integer]
   # @return [Set<String>]
   #
   # @api ppublic
@@ -160,6 +164,7 @@ class RedisQueuedLocks::Swarm
     )
   end
 
+  # @option zombie_ttl [Integer]
   # @return [Set<String>]
   #
   # @api public
@@ -168,6 +173,8 @@ class RedisQueuedLocks::Swarm
     RedisQueuedLocks::Swarm::ZombieInfo.zombie_hosts(rql_client.redis_client, zombie_ttl)
   end
 
+  # @option zombie_ttl [Integer]
+  # @option lock_sacn_size [Integer]
   # @return [Hash<Symbol,Set<String>>]
   #   Format: {
   #     zombie_hosts: <Set<String>>,
@@ -188,7 +195,6 @@ class RedisQueuedLocks::Swarm
     )
   end
 
-  # @option silently [Boolean]
   # @return [NilClass,Hash<Symbol,Symbol|Boolean>]
   #
   # @api public
@@ -220,7 +226,6 @@ class RedisQueuedLocks::Swarm
     end
   end
 
-  # @option silently [Boolean]
   # @return [NilClass,Hash<Symbol,Symbol|Boolean>]
   #
   # @api public

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-15 00:00:00.000000000 Z
+date: 2024-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client