redis_queued_locks 0.0.18 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0993079d1a7cca97094c741d65c4ef1e8a5694184212b6597960e0b3c91d83cb'
-  data.tar.gz: 22535e254fa22db6bfb0225f391e3d4606ad680bb401034fcbdfcd8e93a1fc5c
+  metadata.gz: 281c476c0b1318a3f061e0d22031de92983f4ebd2277bc7e024b2baf998ae559
+  data.tar.gz: 5547ace054290da08fb1eb26e965e2d0ff68dfc9b5c3df0adb8a77069543b8ef
 SHA512:
-  metadata.gz: 7db77251aefc59a83a9727d756774f5eb6b30a156fd058d69ec5170d252cc8fb875b2f213da2e15a4bdf9f5565565aa5ca699545ac0a83dcbc333fbed8c7aec1
-  data.tar.gz: 659c47a6aaa421ade9c7ffaea000a7133c1ba72f5ab0a2e66bc56f5ad72f84f4d9525fc86024e5d52b8196a6dfc7b0a714100462915a91405c97c3b3d77d3e26
+  metadata.gz: a971c732be6ef918ae6e9fc70e4456a076b36a50622cda4e0f2b4d5d3f0cb9479e768852e391b02a6420d3de682ccca7de374cf1410b25be37a5d8cf43a4865c
+  data.tar.gz: ef66b70b7ef28be2b9b2422a94dc89e2fff350ad5d8ce58806f28c7742fa4a3caa5032f64d4817abd52dc4bc2ae77327dcfee79b28f462241c63fb2ddaf992eb

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.0.20] - 2024-03-14
+### Added
+- An ability to provide custom metadata to `lock` and `lock!` methods that will be passed
+  to the instrumentation level inside the `payload` parameter with `:meta` key;
+
+## [0.0.19] - 2024-03-12
+### Added
+- An ability to set the invocation time period to the block of code invoked under
+  the obtained lock;
+
 ## [0.0.18] - 2024-03-04
 ### Changed
 - Semantic results for methods returning `{ ok: true/false, result: Any }` hash objects.

data/README.md

@@ -36,7 +36,9 @@ Each lock request is put into the request queue and processed in order of their
 
 ### Algorithm
 
-- soon
+> Each lock request is put into the request queue and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
+
+**Soon**: detailed explanation.
 
 ---
 
@@ -167,12 +169,14 @@ def lock(
   ttl: config[:default_lock_ttl],
   queue_ttl: config[:default_queue_ttl],
   timeout: config[:try_to_lock_timeout],
+  timed: false,
   retry_count: config[:retry_count],
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
   raise_errors: false,
   fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
+  metadata: nil,
   &block
 )
 ```
@@ -185,6 +189,8 @@ def lock(
   - Lifetime of the acuier's lock request. In seconds.
 - `timeout` - `[Integer,NilClass]`
   - Time period whe should try to acquire the lock (in seconds). Nil means "without timeout".
+- `timed` - `[Boolean]`
+  - Limit the invocation time period of the passed block of code by the lock's TTL.
 - `retry_count` - `[Integer,NilClass]`
   - How many times we should try to acquire a lock. Nil means "infinite retries".
 - `retry_delay` - `[Integer]`
@@ -206,6 +212,8 @@ def lock(
     pods or/and nodes of your application;
   - It is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`
     ivar (accessed via `uniq_dentity` accessor method);
+- `metadata` - `[NilClass,Any]`
+  - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
 - `block` - `[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);
@@ -259,6 +267,7 @@ def lock!(
   retry_jitter: config[:retry_jitter],
   identity: uniq_identity,
   fail_fast: false,
+  metadata: nil,
   &block
 )
 ```
@@ -533,6 +542,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ts` - `integer`/`epoch` - the time when the lock was obtaiend;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+    - `:meta` - `nil`/`Any` - custom metadata passed to the `lock`/`lock!` method;
 - `"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;
@@ -543,6 +553,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ts` - `integer`/`epoch` - the time when lock was obtained;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+    - `:meta` - `nil`/`Any` - custom metadata passed to the `lock`/`lock!` method;
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
   - payload:
@@ -568,6 +579,7 @@ Detalized event semantics and payload structure:
     the acquired lock for long-running blocks of code (that invoked "under" the lock
     whose ttl may expire before the block execution completes);
   - an ability to add custom metadata to the lock and an ability to read this data;
+  - lock prioritization;
 - **Minor**
   - GitHub Actions CI;
   - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;

data/lib/redis_queued_locks/acquier/yield_expire.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::YieldExpire
+  # @param redis [RedisClient] Redis connection manager.
+  # @param lock_key [String] Lock key to be expired.
+  # @param timed [Boolean] Should the lock be wrapped by Tiemlout with with lock's ttl
+  # @param ttl_shift [Float] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
+  # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
+  # @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
+  def yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
+    if block_given?
+      if timed && ttl != nil
+        timeout = ((ttl - ttl_shift) / 1000.0).yield_self { |time| (time < 0) ? 0.0 : time }
+        yield_with_timeout(timeout, lock_key, ttl, &block)
+      else
+        yield
+      end
+    end
+  ensure
+    redis.call('EXPIRE', lock_key, '0')
+  end
+
+  private
+
+  # @param timeout [Float]
+  # @parma lock_key [String]
+  # @param lock_ttl [Integer,NilClass]
+  # @param block [Blcok]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def yield_with_timeout(timeout, lock_key, lock_ttl, &block)
+    ::Timeout.timeout(timeout, &block)
+  rescue ::Timeout::Error
+    raise(RedisQueuedLocks::TimedLockTimeoutError, <<~ERROR_MESSAGE)
+      Passed <timed> block of code exceeded the lock TTL (lock: "#{lock_key}", ttl: #{lock_ttl})
+    ERROR_MESSAGE
+  end
+end

data/lib/redis_queued_locks/acquier.rb

@@ -6,7 +6,7 @@
 module RedisQueuedLocks::Acquier
   require_relative 'acquier/try'
   require_relative 'acquier/delay'
-  require_relative 'acquier/expire'
+  require_relative 'acquier/yield_expire'
   require_relative 'acquier/release'
 
   # @since 0.1.0
@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquier
   # @since 0.1.0
   extend Delay
   # @since 0.1.0
-  extend Expire
+  extend YieldExpire
   # @since 0.1.0
   extend Release
 
@@ -44,6 +44,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 timed [Boolean]
+    #   Limit the invocation time period of the passed block of code by the lock's TTL.
     # @option retry_count [Integer,NilClass]
     #   How many times we should try to acquire a lock. Nil means "infinite retries".
     # @option retry_delay [Integer]
@@ -61,6 +63,8 @@ module RedisQueuedLocks::Acquier
     # @option fail_fast [Boolean]
     #   Should the required lock to be checked before the try and exit immidetly if lock is
     #   already obtained.
+    # @option metadata [NilClass,Any]
+    #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -80,6 +84,7 @@ module RedisQueuedLocks::Acquier
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
@@ -87,6 +92,7 @@ module RedisQueuedLocks::Acquier
       instrumenter:,
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -119,7 +125,7 @@ module RedisQueuedLocks::Acquier
       acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
 
       # Step 2: try to lock with timeout
-      with_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
+      with_acq_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
@@ -140,6 +146,7 @@ module RedisQueuedLocks::Acquier
 
           # Step X: save the intermediate results to the result observer
           acq_process[:result] = result
+          acq_process[:acq_end_time] = acq_end_time
 
           # Step 2.1: analyze an acquirement attempt
           if ok
@@ -149,7 +156,8 @@ module RedisQueuedLocks::Acquier
               ttl: result[:ttl],
               acq_id: result[:acq_id],
               ts: result[:ts],
-              acq_time: acq_time
+              acq_time: acq_time,
+              meta: metadata
             })
 
             # Step 2.1.a: successfully acquired => build the result
@@ -212,7 +220,9 @@ 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, &block)
+            yield_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            ttl_shift = ((yield_time - acq_process[:acq_end_time]) * 1000).ceil(2)
+            yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
           ensure
             acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             acq_process[:hold_time] = (
@@ -227,7 +237,8 @@ module RedisQueuedLocks::Acquier
                 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]
+                acq_time: acq_process[:acq_time],
+                meta: metadata
               })
             end
           end
@@ -526,7 +537,7 @@ module RedisQueuedLocks::Acquier
     #
     # @api private
     # @since 0.1.0
-    def with_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
+    def with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
       ::Timeout.timeout(timeout, &block)
     rescue ::Timeout::Error
       on_timeout.call unless on_timeout == nil

data/lib/redis_queued_locks/client.rb

@@ -71,6 +71,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 timed [Boolean]
+  #   Limit the invocation time period of the passed block of code by the lock's TTL.
   # @option retry_count [Integer,NilClass]
   #   How many times we should try to acquire a lock. Nil means "infinite retries".
   # @option retry_delay [Integer]
@@ -90,6 +92,8 @@ class RedisQueuedLocks::Client
   #   already obtained;
   #   - Should the logic exit immidietly after the first try if the lock was obtained
   #   by another process while the lock request queue was initially empty;
+  # @option metadata [NilClass,Any]
+  #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -103,12 +107,14 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
+    timed: false,
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
     raise_errors: false,
     fail_fast: false,
     identity: uniq_identity,
+    metadata: nil,
     &block
   )
     RedisQueuedLocks::Acquier.acquire_lock!(
@@ -121,6 +127,7 @@ class RedisQueuedLocks::Client
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
@@ -128,6 +135,7 @@ class RedisQueuedLocks::Client
       instrumenter: config[:instrumenter],
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
   end
@@ -141,11 +149,13 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
+    timed: false,
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
     fail_fast: false,
     identity: uniq_identity,
+    metadata: nil,
     &block
   )
     lock(
@@ -153,12 +163,14 @@ class RedisQueuedLocks::Client
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
       raise_errors: true,
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
   end

data/lib/redis_queued_locks/errors.rb

@@ -20,4 +20,8 @@ module RedisQueuedLocks
   # @api public
   # @since 0.1.0
   LockAcquiermentRetryLimitError = Class.new(Error)
+
+  # @api pulic
+  # @since 0.1.0
+  TimedLockTimeoutError = Class.new(Error)
 end

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.18
+  version: 0.0.20
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-04 00:00:00.000000000 Z
+date: 2024-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -57,9 +57,9 @@ files:
 - lib/redis_queued_locks.rb
 - lib/redis_queued_locks/acquier.rb
 - lib/redis_queued_locks/acquier/delay.rb
-- lib/redis_queued_locks/acquier/expire.rb
 - lib/redis_queued_locks/acquier/release.rb
 - lib/redis_queued_locks/acquier/try.rb
+- lib/redis_queued_locks/acquier/yield_expire.rb
 - lib/redis_queued_locks/client.rb
 - lib/redis_queued_locks/data.rb
 - lib/redis_queued_locks/debugger.rb

data/lib/redis_queued_locks/acquier/expire.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# @api private
-# @since 0.1.0
-module RedisQueuedLocks::Acquier::Expire
-  # @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
-  def yield_with_expire(redis, lock_key, &block)
-    yield if block_given?
-  ensure
-    redis.call('EXPIRE', lock_key, '0')
-  end
-end