redis_queued_locks 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f78a90d3830a3797bfd973b8ce48a879ba8400c3daec8827c0c14c25c650bb3
-  data.tar.gz: a8e09fae141ff16d142234a4200c86f05abea787fb627e23b4187dd11fa06086
+  metadata.gz: e984603ea8f509f8e5f7f685c356d1f838b16bc950e1de83ff8f66e6afa83fcf
+  data.tar.gz: 1b2eee0f32c911caecf08214b2b404d620ffb10501ae72d7721235b64fc02362
 SHA512:
-  metadata.gz: fe28a66ec0d028453a0e43f2e140b907a100a70b8a547af8067f45f60392339dd9d0540ef9b8638d0bc9588dd0152f4e21ac488d031170cb872679c7ed4bc34a
-  data.tar.gz: 6608fc1f6a9b2b2000254ba0b4a39d5d16c50f9265bcf58c7b138066e08c29c32d31047e3419db09aa0bfda88c09af10111254c3bf2ba35df775248f2d732d63
+  metadata.gz: b7e2d574eeeff4a9a235f39ee25bde152880dcd12e7066196a8304e54098480ef05672edd89a6931ece225711b96602f23ce76304c555dbd623d30099e35ca0a
+  data.tar.gz: d7f5075bbf136e672ebb1632da5c6a78b2b72886bc1d5e8b0d9425cf38b14f5eef5a097fdc835c78f5f2d26885512279926a33bdbdb559151b875453d5312c9e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [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;

data/README.md

@@ -5,13 +5,38 @@ Distributed lock implementation with "lock acquisition queue" capabilities based
 ## Instrumentation events
 
 - `"redis_queued_locks.lock_obtained"`
-  - the moment when the lock was 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 ;
+    - `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
 

data/lib/redis_queued_locks/acquier/release.rb

@@ -8,32 +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,
       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))
@@ -42,6 +50,8 @@ module RedisQueuedLocks::Acquier::Release
 
     # Step B: release all locks
     redis.pipelined do |pipeline|
+      rel_lock_cnt += 1
+
       redis.scan(
         'MATCH',
         RedisQueuedLocks::Resource::LOCK_PATTERN,
@@ -50,5 +60,7 @@ module RedisQueuedLocks::Acquier::Release
         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.rb

@@ -37,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]
@@ -90,7 +90,9 @@ module RedisQueuedLocks::Acquier
         tries: 0,
         acquired: false,
         result: nil,
-        acq_time: nil # NOTE: in milliseconds
+        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) }
 
@@ -118,7 +120,7 @@ module RedisQueuedLocks::Acquier
 
           # Step 2.1: analyze an acquirement attempt
           if ok
-            # INSTRUMENT: lock obtained
+            # Step X (instrumentation): lock obtained
             instrumenter.notify('redis_queued_locks.lock_obtained', {
               lock_key: result[:lock_key],
               ttl: result[:ttl],
@@ -160,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) # INSTRUMENT: lock release
+          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
@@ -181,16 +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)
 
-      # INSTRUMENT: lock release
+      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
 
@@ -200,13 +232,25 @@ 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)
-      # INSTRUMENT: all locks released
+    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
 

data/lib/redis_queued_locks/client.rb

@@ -60,9 +60,9 @@ 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]
@@ -147,14 +147,23 @@ class RedisQueuedLocks::Client
   # @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
 
+  # @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/version.rb

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

metadata

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