redis_queued_locks 0.0.19 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c77f863ddb9f33c75a636ea12281ce1f4df1215d50f43b113b5be5f79b679526
-  data.tar.gz: 9585690846e55b141e089d26ac160f6481297cfa6f43d21df1403411903221be
+  metadata.gz: 281c476c0b1318a3f061e0d22031de92983f4ebd2277bc7e024b2baf998ae559
+  data.tar.gz: 5547ace054290da08fb1eb26e965e2d0ff68dfc9b5c3df0adb8a77069543b8ef
 SHA512:
-  metadata.gz: 9e132a1464d92aa59539d5489d5b7d777399de6c38f313cbad063b819e0e32503591532eb010f5c6b87da41096172e9dde8f5fa2fc84623ca2256b84cd3fa98d
-  data.tar.gz: ea8dc9808a5c16697e5606ce8394c987ceb8df4f561fbf06250bd7669188665f56825a582e9c82240a52b6376767eedda9afeed588f960498fb32070466c512c
+  metadata.gz: a971c732be6ef918ae6e9fc70e4456a076b36a50622cda4e0f2b4d5d3f0cb9479e768852e391b02a6420d3de682ccca7de374cf1410b25be37a5d8cf43a4865c
+  data.tar.gz: ef66b70b7ef28be2b9b2422a94dc89e2fff350ad5d8ce58806f28c7742fa4a3caa5032f64d4817abd52dc4bc2ae77327dcfee79b28f462241c63fb2ddaf992eb

data/CHANGELOG.md

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

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.
 
 ---
 
@@ -174,6 +176,7 @@ def lock(
   raise_errors: false,
   fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
+  metadata: nil,
   &block
 )
 ```
@@ -209,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);
@@ -262,6 +267,7 @@ def lock!(
   retry_jitter: config[:retry_jitter],
   identity: uniq_identity,
   fail_fast: false,
+  metadata: nil,
   &block
 )
 ```
@@ -536,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;
@@ -546,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:
@@ -571,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.rb

@@ -63,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]
@@ -90,6 +92,7 @@ module RedisQueuedLocks::Acquier
       instrumenter:,
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -153,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
@@ -233,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

data/lib/redis_queued_locks/client.rb

@@ -92,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]
@@ -112,6 +114,7 @@ class RedisQueuedLocks::Client
     raise_errors: false,
     fail_fast: false,
     identity: uniq_identity,
+    metadata: nil,
     &block
   )
     RedisQueuedLocks::Acquier.acquire_lock!(
@@ -132,6 +135,7 @@ class RedisQueuedLocks::Client
       instrumenter: config[:instrumenter],
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
   end
@@ -151,6 +155,7 @@ class RedisQueuedLocks::Client
     retry_jitter: config[:retry_jitter],
     fail_fast: false,
     identity: uniq_identity,
+    metadata: nil,
     &block
   )
     lock(
@@ -165,6 +170,7 @@ class RedisQueuedLocks::Client
       raise_errors: true,
       identity:,
       fail_fast:,
+      metadata:,
       &block
     )
   end

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 0.0.19
-  VERSION = '0.0.19'
+  # @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.19
+  version: 0.0.20
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-12 00:00:00.000000000 Z
+date: 2024-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client