redis_queued_locks 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e984603ea8f509f8e5f7f685c356d1f838b16bc950e1de83ff8f66e6afa83fcf
-  data.tar.gz: 1b2eee0f32c911caecf08214b2b404d620ffb10501ae72d7721235b64fc02362
+  metadata.gz: 6e1e1a54762132f92451d595938cb467b7b644dffc0817abe99209e1f92160f8
+  data.tar.gz: 297eec3d7fcee35d12e7f3509e8e3dfd4b8b3c52889c7570a79cd6a30f45eda4
 SHA512:
-  metadata.gz: b7e2d574eeeff4a9a235f39ee25bde152880dcd12e7066196a8304e54098480ef05672edd89a6931ece225711b96602f23ce76304c555dbd623d30099e35ca0a
-  data.tar.gz: d7f5075bbf136e672ebb1632da5c6a78b2b72886bc1d5e8b0d9425cf38b14f5eef5a097fdc835c78f5f2d26885512279926a33bdbdb559151b875453d5312c9e
+  metadata.gz: 6d2c64622bd3b8465a749b5f6a8050d5fd1d5b623990f91421f91004c444baab12114964ded28d5ac0fa43fed56f3e893798feb31b00ab173d536e57fcfdfaa4
+  data.tar.gz: 02ee9d8742ffd3a7b16b8c23b8d4c4f58a8cb1b9db4d215ece4bf34de0c79830bd3417186b2d75dbbd48f6845d736361af7503f641e7faa16d139cbe193263d3

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.0.4] - 2024-02-26
+### Changed
+- changed default configuration values of `RedisQueuedLocks::Client` config;
+
+## [0.0.3] - 2024-02-26
+### Changed
+- Instrumentation events:
+  - `"redis_queued_locks.explicit_all_locks_release"`
+    - re-factored with fully pipelined invocation;
+    - removed `rel_queue_cnt` and `rel_lock_cnt` because of the pipelined invocation
+      misses the concrete results and now we can receive only "released redis keys count";
+    - adde `rel_keys` payload data (released redis keys);
+
 ## [0.0.2] - 2024-02-26
 ### Added
 - Instrumentation events:

data/README.md

@@ -2,6 +2,67 @@
 
 Distributed lock implementation with "lock acquisition queue" capabilities based on the Redis Database.
 
+## Configuration
+
+```ruby
+redis_client = RedisClient.config.new_pool # NOTE: provide your own RedisClient instance
+
+clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
+  # (default: 3) (supports nil)
+  # - nil means "infinite retries" and you are only limited by the "try_to_lock_timeout" config;
+  config.retry_count = 3
+
+  # (milliseconds) (default: 200)
+  config.retry_delay = 200
+
+  # (milliseconds) (default: 50)
+  config.retry_jitter = 50
+
+  # (seconds) (supports nil)
+  # - nil means "no timeout" and you are only limited by "retry_count" config;
+  config.try_to_lock_timeout = 10
+
+  # (milliseconds) (default: 1)
+  # - expiration precision. affects the ttl (ttl + precision);
+  config.exp_precision = 1
+
+  # (milliseconds) (default: 5_000)
+  # - lock's time to live
+  config.default_lock_ttl = 5_000
+
+  # (seconds) (default: 15)
+  # - lock request timeout. after this timeout your lock request in queue will be requeued;
+  config.default_queue_ttl = 15
+
+  # (default: 100)
+  # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic;
+  # - affects the performancs capabilites (redis, rubyvm);
+  config.lock_release_batch_size = 100
+
+  # (default: RedisQueuedLocks::Instrument::VoidNotifier)
+  # - instrumentation layer;
+  # - you can provde your own instrumenter with `#notify(event, payload = {})`
+  #   - event: <string> requried;
+  #   - payload: <hash> requried;
+  # - disabled by default via VoidNotifier;
+  config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
+end
+```
+
+## Usage
+
+```ruby
+redis_clinet = RedisClient.config.new_pool # NOTE: provide your ounw RedisClient instance
+rq_lock = RedisQueuedLocks::Client.new(redis_client) do |config|
+  # NOTE: some your application-related configs
+end
+```
+
+- `#lock`
+- `#lock!`
+- `#unlock`
+- `#clear_locks`
+
 ## Instrumentation events
 
 - `"redis_queued_locks.lock_obtained"`
@@ -22,7 +83,6 @@ Distributed lock implementation with "lock acquisition queue" capabilities based
     - `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:
@@ -31,13 +91,8 @@ Distributed lock implementation with "lock acquisition queue" capabilities based
     - `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`);
+  - an event signalizes about the explicit all locks release (invoked via `RedisQueuedLock#clear_locks`);
   - payload:
-    - `rel_time` - `float`/`milliseconds` - time when the locks was released
+    - `rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
     - `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);
+    - `rel_keys` - `integer` - released redis keys count (`released queu keys` + `released lock keys`);

data/lib/redis_queued_locks/acquier/delay.rb

@@ -3,6 +3,8 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::Delay
+  # Sleep with random time-shifting (it is necessary for empty-time-slot lock acquirement).
+  #
   # @param retry_delay [Integer] In milliseconds
   # @param retry_jitter [Integer] In milliseconds
   # @return [void]

data/lib/redis_queued_locks/acquier/expire.rb

@@ -3,10 +3,10 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::Expire
-  # @param redis [RedisClient]
-  # @param lock_key [String]
-  # @param block [Block]
-  # @return [void]
+  # @param redis [RedisClient] Redis connection manager.
+  # @param lock_key [String] Lock key to be expired.
+  # @param block [Block] Custom logic that should be invoked unter the obtained lock.
+  # @return [Any,NilClass] nil is returned no block parametr is provided.
   #
   # @api private
   # @since 0.1.0

data/lib/redis_queued_locks/acquier/release.rb

@@ -30,37 +30,31 @@ module RedisQueuedLocks::Acquier::Release
   # @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,
-      count: batch_size
-    ) do |lock_queue|
-      rel_queue_cnt += 1
-      rel_lock_cnt += 1
-
-      redis.pipelined do |pipeline|
+    result = redis.pipelined do |pipeline|
+      # Step A: release all queus and their related locks
+      redis.scan(
+        'MATCH',
+        RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+        count: batch_size
+      ) do |lock_queue|
+        puts "RELEASE (lock_queue): #{lock_queue}"
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
-        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue))
+        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), "0")
       end
-    end
-
-    # Step B: release all locks
-    redis.pipelined do |pipeline|
-      rel_lock_cnt += 1
 
+      # Step B: release all locks
       redis.scan(
         'MATCH',
         RedisQueuedLocks::Resource::LOCK_PATTERN,
         count: batch_size
       ) do |lock_key|
+        puts "RELEASE (lock_key): #{lock_key}"
         pipeline.call('EXPIRE', lock_key, '0')
       end
     end
 
-    { ok: true, result: { rel_queue_cnt:, rel_lock_cnt: } }
+    rel_keys = result.count { |red_res| red_res == 0 }
+
+    { ok: true, result: { rel_keys: rel_keys } }
   end
 end

data/lib/redis_queued_locks/acquier.rb

@@ -43,8 +43,8 @@ module RedisQueuedLocks::Acquier
     #   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]
-    #   How many times we should try to acquire a lock.
+    # @option retry_count [Integer,NilClass]
+    #   How many times we should try to acquire a lock. Nil means "infinite retries".
     # @option retry_delay [Integer]
     #   A time-interval between the each retry (in milliseconds).
     # @option retry_jitter [Integer]
@@ -113,7 +113,7 @@ module RedisQueuedLocks::Acquier
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-          acq_time = ((acq_end_time - acq_start_time) * 1_000).ceil
+          acq_time = ((acq_end_time - acq_start_time) * 1_000).ceil(2)
 
           # Step X: save the intermediate results to the result observer
           acq_process[:result] = result
@@ -139,20 +139,20 @@ module RedisQueuedLocks::Acquier
             acq_process[:acquired] = true
             acq_process[:should_try] = false
             acq_process[:acq_time] = acq_time
+            acq_process[:acq_end_time] = acq_end_time
           else
             # Step 2.1.b: failed acquirement => retry
             acq_process[:tries] += 1
 
-            if acq_process[:tries] >= retry_count
+            if retry_count != nil && acq_process[:tries] >= retry_count
               # NOTE: reached the retry limit => quit from the loop
               acq_process[:should_try] = false
               # NOTE: reached the retry limit => dequeue from the lock queue
               acq_dequeue.call
-            else
+            elsif delay_execution(retry_delay, retry_jitter)
               # NOTE:
               #   delay the exceution in order to prevent chaotic attempts
               #   and to allow other processes and threads to obtain the lock too.
-              delay_execution(retry_delay, retry_jitter)
             end
           end
         end
@@ -163,23 +163,24 @@ module RedisQueuedLocks::Acquier
         # Step 3.a: acquired successfully => run logic or return the result of acquirement
         if block_given?
           begin
-            yield_with_expire(redis, lock_key, instrumenter, &block)
+            yield_with_expire(redis, lock_key, &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
+            acq_process[:hold_time] = (
+              (acq_process[:rel_time] - acq_process[:acq_end_time]) * 1000
+            ).ceil(2)
 
             # 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]
-            })
+            run_non_critical do
+              instrumenter.notify('redis_queued_locks.lock_hold_and_release', {
+                hold_time: acq_process[:hold_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
           end
         else
           { ok: true, result: acq_process[:lock_info] }
@@ -211,17 +212,19 @@ module RedisQueuedLocks::Acquier
       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)
+      fully_release_lock(redis, lock_key, lock_key_queue) => { ok:, result: }
       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
+      rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil(2)
 
-      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
-      })
+      run_non_critical do
+        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
+        })
+      end
 
       { ok: true, result: result }
     end
@@ -239,17 +242,18 @@ module RedisQueuedLocks::Acquier
     # @since 0.1.0
     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)
+      fully_release_all_locks(redis, batch_size) => { ok:, result: }
       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
+      rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil(2)
 
-      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]
-      })
+      run_non_critical do
+        instrumenter.notify('redis_queued_locks.explicit_all_locks_release', {
+          at: time_at,
+          rel_time: rel_time,
+          rel_keys: result[:rel_keys]
+        })
+      end
 
       { ok: true, result: result }
     end
@@ -279,6 +283,15 @@ module RedisQueuedLocks::Acquier
         ERROR_MESSAGE
       end
     end
+
+    # @param block [Block]
+    # @return [Any]
+    #
+    # @api private
+    # @since 0.1.0
+    def run_non_critical(&block)
+      yield rescue nil
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/redis_queued_locks/client.rb

@@ -10,25 +10,25 @@ class RedisQueuedLocks::Client
     setting :retry_count, 3
     setting :retry_delay, 200 # NOTE: milliseconds
     setting :retry_jitter, 50 # NOTE: milliseconds
-    setting :default_timeout, 10 # NOTE: seconds
+    setting :try_to_lock_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 :default_lock_ttl, 5_000 # NOTE: milliseconds
+    setting :default_queue_ttl, 15 # 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_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay', :integer)
     validate('retry_jitter', :integer)
-    validate('default_timeout', :integer)
+    validate('try_to_lock_timeout') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     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) }
+    validate('instrumenter') { |val| RedisQueuedLocks::Instrument.valid_interface?(val) }
   end
 
   # @return [RedisClient]
@@ -63,8 +63,8 @@ class RedisQueuedLocks::Client
   #   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_count [Integer,NilClass]
+  #   How many times we should try to acquire a lock. Nil means "infinite retries".
   # @option retry_delay [Integer]
   #   A time-interval between the each retry (in milliseconds).
   # @option retry_jitter [Integer]
@@ -86,7 +86,7 @@ class RedisQueuedLocks::Client
     thread_id: RedisQueuedLocks::Resource.get_thread_id,
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
-    timeout: config[:default_timeout],
+    timeout: config[:try_to_lock_timeout],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],

data/lib/redis_queued_locks/version.rb

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

metadata

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