redis_queued_locks 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0067915f812330a031b51bc20300a13eee31aa2628aa2b26c90524c58d80ab60'
-  data.tar.gz: f322cbff42c80656ad09d075008c48461db991c153ab04b42e4187f54bcc6bce
+  metadata.gz: 5b4ae233fe0c41b159f78f44fde1623d54e5bb80bc675c06e11d89741f41cc8d
+  data.tar.gz: 0c79574d32f3e807d7005e64616ce316be64e3e8553df8e65d15e821ee3e0559
 SHA512:
-  metadata.gz: fbe61d02314ec926529a30cb3771903199897b798f386ff6a5ebb562d3857b92c11d5579a4d6cc9219fa64e152ff1e4f6aeb1ceb98cf8eae094c443b8ec2f6b9
-  data.tar.gz: 3462b766ffb13ca57d21caa7d4725b076a3dc6c594601288f8c7593cb496f58d3ce4b66082035d8ab4bbfa3eba395db475995cacb3a4eb588b03ab06a25eef27
+  metadata.gz: 9a0cbdc2c84e9b5da48008a881fe2994bbdaba859d1795cd599d272acb6004c445b3784c311d90f1924bf74c161a58784d6025b3185f3da02f6f97486783eb81
+  data.tar.gz: 61c730ae6bdd25a3a49ca4da36388e9c08280e36eb83de6edaf6dc879b447c5109e6321e7e8b160a973d5eb8abfcb35d8090984f26aca04c738ad7a6e797c967

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.0.14] - 2024-02-28
+### Changed
+- Minor documentation updates;
+
 ## [0.0.13] - 2024-02-27
 ### Changed
 - Minor development updates;

data/README.md

@@ -2,7 +2,7 @@
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
-Each lock request is put into a request queue and processed in order of their priority (FIFO).
+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.
 
 ---
 
@@ -145,6 +145,8 @@ end
 
 - If block is passed the obtained lock will be released after the block execution or the lock's ttl (what will happen first);
 - If block is not passed the obtained lock will be released after lock's ttl;
+- If block is passed the block's yield result will be returned;
+- If block is not passed the lock information will be returned;
 
 ```ruby
 def lock(
@@ -191,25 +193,30 @@ def lock(
   - If block is **not passed** the obtained lock will be released after it's ttl;
 
 Return value:
-- `[Hash<Symbol,Any>]` Format: `{ ok: true/false, result: Symbol/Hash }`;
-- for successful lock obtaining:
-  ```ruby
-  {
-    ok: true,
-    result: {
-      lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
-      acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
-      ts: Integer, # time (epoch) when lock was obtained (integer)
-      ttl: Integer # lock's time to live in milliseconds (integer)
+
+- If block is passed the block's yield result will be returned;
+- If block is not passed the lock information will be returned;
+- Lock information result:
+  - Signature: `[yield, Hash<Symbol,Boolean|Hash<Symbol,Numeric|String>>]`
+  - Format: `{ ok: true/false, result: <Symbol|Hash<Symbol,Hash>> }`;
+  - for successful lock obtaining:
+    ```ruby
+    {
+      ok: true,
+      result: {
+        lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
+        acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
+        ts: Integer, # time (epoch) when lock was obtained (integer)
+        ttl: Integer # lock's time to live in milliseconds (integer)
+      }
     }
-  }
-  ```
-- for failed lock obtaining:
-  ```ruby
-  { ok: false, result: :timeout_reached }
-  { ok: false, result: :retry_count_reached }
-  { ok: false, result: :unknown }
-  ```
+    ```
+  - for failed lock obtaining:
+    ```ruby
+    { ok: false, result: :timeout_reached }
+    { ok: false, result: :retry_count_reached }
+    { ok: false, result: :unknown }
+    ```
 
 ---
 
@@ -277,6 +284,14 @@ rql.lock_info("your_lock_name")
     - `acq_id` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity by default);
     - `score` - `float`/`epoch` - time when the lock request was made (epoch);
 
+```
+| Returns an information about the required lock queue by the lock name. The result
+| represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
+| lock acquirers and their position in queue. Async nature with redis communcation can lead
+| the situation when the queue becomes empty during the queue data extraction. So sometimes
+| you can receive the lock queue info with empty queue value (an empty array).
+```
+
 ```ruby
 rql.queue_info("your_lock_name")
 
@@ -327,7 +342,7 @@ def unlock(lock_name)
   - the lock name that should be released.
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
+- `[Hash<Symbol,Numeric|String>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
 
 ```ruby
 {
@@ -352,10 +367,10 @@ def clear_locks(batch_size: config[:lock_release_batch_size])
 ```
 
 - `batch_size` - `[Integer]`
-  - batch of cleared locks and lock queus unde the one pipelined redis command;
+  - the size of batch of locks and lock queus that should be cleared under the one pipelined redis command at once;
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
+- `[Hash<Symbol,Numeric>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
 
 ```ruby
 {

data/lib/redis_queued_locks/acquier/try.rb

@@ -104,7 +104,7 @@ module RedisQueuedLocks::Acquier::Try
           )
 
           # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
-          transact.call('PEXPIRE', lock_key, ttl) # NOTE: in seconds
+          transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
         end
       end
     end

data/lib/redis_queued_locks/acquier.rb

@@ -60,8 +60,9 @@ module RedisQueuedLocks::Acquier
     #   represented as 10 bytes hexstr.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
-    # @return [Hash<Symbol,Any>]
-    #   Format: { ok: true/false, result: Any }
+    # @return [Hash<Symbol,Any>,yield]
+    #  - Format: { ok: true/false, result: Any }
+    #  - If block is given the result of block's yeld will be returned.
     #
     # @api private
     # @since 0.1.0
@@ -363,7 +364,7 @@ module RedisQueuedLocks::Acquier
     # Returns an information about the required lock queue by the lock name. The result
     # represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
     # lock acquirers and their position in queue. Async nature with redis communcation can lead
-    # the sitation when the queue becomes empty during the queue data extraction. So sometimes
+    # the sitaution when the queue becomes empty during the queue data extraction. So sometimes
     # you can receive the lock queue info with empty queue.
     #
     # @param redis_client [RedisClient]

data/lib/redis_queued_locks/client.rb

@@ -43,6 +43,8 @@ class RedisQueuedLocks::Client
   # @api private
   # @since 0.1.0
   attr_accessor :uniq_identity
+  # NOTE: attr_access is chosen intentionally in order to have an ability to change
+  #  uniq_identity values for debug purposes in runtime;
 
   # @param redis_client [RedisClient]
   #   Redis connection manager, which will be used for the lock acquierment and distribution.
@@ -84,7 +86,8 @@ class RedisQueuedLocks::Client
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [Hash<Symbol,Any>,yield]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  #   - Format: { ok: true/false, result: Symbol/Hash }.
+  #   - If block is given the result of block's yeld will be returned.
   #
   # @api public
   # @since 0.1.0

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Rustam Ibragimov
@@ -92,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.1
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.