redis_queued_locks 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e98a72e1519c54d21a6273176a7d8a3bd9fa3033b7f30ca73fdca5a4335341d
-  data.tar.gz: b2cf62db6016bd456a379feb3703989cc4a481f2eed4103c5c27a60bec624d46
+  metadata.gz: 4846c7a27c9ce2108903a9b9b9250a38aa18ae34be6da85b4055bfe9c20371bb
+  data.tar.gz: 0346d8a0c4d43490ea0fcf79c7048e70c480285b18f26f84b06ad24fe42dc9fc
 SHA512:
-  metadata.gz: d90c848b5fb00614c3f61719d470d7a2dae008d3b6349c395674fe7bf262feea09795dafc74756a16426f499652e9cb0dcb4eef8b0dc9e2c1cc8abff2a1345d1
-  data.tar.gz: ccc6e73175a2c41988303e3ea73feeacf95833b8d318dc1318c91f800d656ea157aeca62d7eba491ca489253a01ba4489f6a4c254c32f54ef3a540c9312ca179
+  metadata.gz: cbf5bd49d6c3b912ff8e3b8061cae4e2b1eaea00f913c8f217058168e7008f3c4daaeef0888ca22bce22d318742db1890c8524293e20734b4dea506fc3eeae10
+  data.tar.gz: 744519a43e3f1eb98527cbcb5495700b16a6ea94de95732baf8027debc14df7e5fa0394f804a9360383eb9168d3975794b46c4a0a6c45d1b769fd0c94e1700b5

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.0.8] - 2024-02-27
+### Added
+- `RedisQueuedLock::Client#locked?`
+- `RedisQueuedLock::Client#queued?`
+- `RedisQueuedLock::Client#lock_info`
+- `RedisQueuedLock::Client#queue_info`
+
+## [0.0.7] - 2024-02-27
+### Changed
+- Minor documentation updates;
+
 ## [0.0.6] - 2024-02-27
 ### Changed
 - Major documentation updates;

data/README.md

@@ -1,6 +1,7 @@
 # RedisQueuedLocks
 
-Distributed lock implementation with "lock acquisition queue" capabilities based on the Redis Database.
+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).
 
 ---
@@ -14,11 +15,15 @@ Each lock request is put into a request queue and processed in order of their pr
 - [Usage](#usage)
   - [lock](#lock---obtain-a-lock)
   - [lock!](#lock---exeptional-lock-obtaining)
+  - [lock_info](#lock_info)
+  - [queue_info](#queue_info)
+  - [locked?](#locked)
+  - [queued?](#queued)
   - [unlock](#unlock---release-a-lock)
   - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
-- [TODO](#todo)
+- [Roadmap](#roadmap)
 - [Contributing](#contributing)
 - [License](#license)
 - [Authors](#authors)
@@ -65,6 +70,7 @@ rq_lock_client = RedisQueuedLocks::Client.new(redis_client) do |config|
 end
 
 # Step 3: start to work with locks :)
+rq_lock_client.lock("some-lock") { puts "Hello, lock!" }
 ```
 
 ---
@@ -122,6 +128,10 @@ end
 
 - [lock](#lock---obtain-a-lock)
 - [lock!](#lock---exeptional-lock-obtaining)
+- [lock_info](#lock_info)
+- [queue_info](#queue_info)
+- [locked?](#locked)
+- [queued?](#queued)
 - [unlock](#unlock---release-a-lock)
 - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
 
@@ -166,9 +176,11 @@ def lock(
 - `instrumenter` - `[#notify]`
   - See RedisQueuedLocks::Instrument::ActiveSupport for example.
 - `raise_errors` - `[Boolean]`
-  - Raise errors on library-related limits such as timeout or failed lock obtain.
+  - Raise errors on library-related limits such as timeout or retry count limit.
 - `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);
+  - 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 }`;
@@ -191,7 +203,6 @@ Return value:
   { ok: false, result: :unknown }
   ```
 
-
 ---
 
 #### #lock! - exceptional lock obtaining
@@ -219,6 +230,83 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 
 ---
 
+#### #lock_info
+
+- get the lock information;
+- returns `nil` if lock does not exist;
+- lock data (`Hash<Symbol,String|Integer>`):
+  - `lock_key` - `string` - lock key in redis;
+  - `acq_id` - `string` - acquier identifier (process_id/thread_id by default);
+  - `ts` - `integer`/`epoch` - the time lock was obtained;
+  - `init_ttl` - `integer` - (milliseconds) initial lock key ttl;
+  - `rem_ttl` - `integer` - (milliseconds) remaining lock key ttl;
+
+```ruby
+rql.lock_info("your_lock_name")
+
+# =>
+{
+  lock_key: "rql:lock:your_lock_name",
+  acq_id: "rql:acq:123/456",
+  ts: 123456789,
+  ini_ttl: 123456789,
+  rem_ttl: 123456789
+}
+```
+
+---
+
+#### #queue_info
+
+- get the lock queue information;
+- queue represents the ordered set of lock key reqests:
+  - set is ordered by score in ASC manner (inside the Redis Set);
+  - score is represented as a timestamp when the lock request was made;
+  - represents the acquier identifier and their score as an array of hashes;
+- returns `nil` if lock queue does not exist;
+- lock queue data (`Hash<Symbol,String|Array<Hash<Symbol,String|Numeric>>`):
+  - `lock_queue` - `string` - lock queue key in redis;
+  - `queue` - `array` - an array of lock requests (array of hashes):
+    - `acq_id` - `string` - acquier identifier (process_id/thread_id by default);
+    - `score` - `float`/`epoch` - time when the lock request was made (epoch);
+
+```ruby
+rql.queue_info("your_lock_name")
+
+# =>
+{
+  lock_queue: "rql:lock_queue:your_lock_name",
+  queue: [
+    { acq_id: "rql:acq:123/456", score: 1},
+    { acq_id: "rql:acq:123/567", score: 2},
+    { acq_id: "rql:acq:555/329", score: 3},
+    # ...etc
+  ]
+}
+```
+
+---
+
+#### #locked?
+
+- is the lock obtaied or not?
+
+```ruby
+rql.locked?("your_lock_name") # => true/false
+```
+
+---
+
+#### #queued?
+
+- is the lock queued for obtain / has requests for obtain?
+
+```ruby
+rql.queued?("your_lock_name") # => true/false
+```
+
+---
+
 #### #unlock - release a lock
 
 - release the concrete lock with lock request queue;
@@ -276,9 +364,9 @@ Return:
 
 ## Instrumentation
 
-An instrumentation layer is incapsulated in `instrumenter` object stored in configurations.
+An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
 
-Instrumenter object should provide `notify(event, payload)` method with following signarue:
+Instrumenter object should provide `notify(event, payload)` method with the following signarue:
 
 - `event` - `string`;
 - `payload` - `hash<Symbol,Any>`;
@@ -286,7 +374,7 @@ Instrumenter object should provide `notify(event, payload)` method with followin
 `redis_queued_locks` provides two instrumenters:
 
 - `RedisQueuedLocks::Instrument::ActiveSupport` - `ActiveSupport::Notifications` instrumenter
-  that instrument events via `ActiveSupport::Notifications` api;
+  that instrument events via `ActiveSupport::Notifications` API;
 - `RedisQueuedLocks::Instrument::VoidNotifier` - instrumenter that does nothing;
 
 By default `RedisQueuedLocks::Client` is configured with the void notifier (which means "instrumentation is disabled").
@@ -338,11 +426,14 @@ Detalized event semantics and payload structure:
 
 ---
 
-## TODO
+## Roadmap
 
-- `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
-- `100%` test coverage;
-- better code stylization and interesting refactorings :)
+- **Major**
+  - Semantic Error objects for unexpected Redis errors;
+  - `100%` test coverage;
+- **Minor**
+  - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
+  - better code stylization and interesting refactorings;
 
 ---
 

data/lib/redis_queued_locks/acquier/release.rb

@@ -38,7 +38,7 @@ module RedisQueuedLocks::Acquier::Release
         count: batch_size
       ) do |lock_queue|
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
-        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), "0")
+        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
       end
 
       # Step B: release all locks

data/lib/redis_queued_locks/acquier/try.rb

@@ -95,7 +95,13 @@ module RedisQueuedLocks::Acquier::Try
           )
 
           # Step 6.2: acquire a lock and store an info about the acquier
-          transact.call('HSET', lock_key, 'acq_id', acquier_id, 'ts', (timestamp = Time.now.to_i))
+          transact.call(
+            'HSET',
+            lock_key,
+            'acq_id', acquier_id,
+            'ts', (timestamp = Time.now.to_i),
+            'ini_ttl', ttl
+          )
 
           # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
           transact.call('PEXPIRE', lock_key, ttl) # NOTE: in seconds

data/lib/redis_queued_locks/acquier.rb

@@ -271,6 +271,121 @@ module RedisQueuedLocks::Acquier
       { ok: true, result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time } }
     end
 
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 0.1.0
+    def locked?(redis_client, lock_name)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      redis_client.call('EXISTS', lock_key) == 1
+    end
+
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 0.1.0
+    def queued?(redis_client, lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+      redis_client.call('EXISTS', lock_key_queue) == 1
+    end
+
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Hash<Symbol,String|Numeric>,NilClass]
+    #   - `nil` is returned when lock key does not exist or expired;
+    #   - result format: {
+    #     lock_key: "rql:lock:your_lockname", # acquired lock key
+    #     acq_id: "rql:acq:process_id/thread_id", # lock acquier identifier
+    #     ts: 123456789, # <locked at> time stamp (epoch)
+    #     ini_ttl: 123456789, # initial lock key ttl (milliseconds),
+    #     rem_ttl: 123456789, # remaining lock key ttl (milliseconds)
+    #   }
+    #
+    # @api private
+    # @since 0.1.0
+    def lock_info(redis_client, lock_name)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+
+      result = redis_client.multi(watch: [lock_key]) do |transact|
+        transact.call('HGETALL', lock_key)
+        transact.call('PTTL', lock_key)
+      end
+
+      if result == nil
+        # NOTE:
+        #   - nil result means that during transaction invocation the lock is changed (CAS):
+        #     - lock is expired;
+        #     - lock is released;
+        #     - lock is expired + re-obtained;
+        nil
+      else
+        hget_cmd_res = result[0]
+        pttl_cmd_res = result[1]
+
+        if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
+          nil
+        else
+          # NOTE: the result of MULTI-command is an array of results of each internal command
+          #   - result[0] (HGETALL) (Hash<String,String>)
+          #   - result[1] (PTTL) (Integer)
+          {
+            lock_key: lock_key,
+            acq_id: hget_cmd_res['acq_id'],
+            ts: Integer(hget_cmd_res['ts']),
+            ini_ttl: Integer(hget_cmd_res['ini_ttl']),
+            rem_ttl: ((pttl_cmd_res == -1) ? Infinity : pttl_cmd_res)
+          }
+        end
+      end
+    end
+
+    # 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
+    # you can receive the lock queue info with empty queue.
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Hash<Symbol,String|Array<Hash<Symbol,String|Float>>,NilClass]
+    #   - `nil` is returned when lock queue does not exist;
+    #   - result format: {
+    #     lock_queue: "rql:lock_queue:your_lock_name", # lock queue key in redis,
+    #     queue: [
+    #       { acq_id: "rql:acq:process_id/thread_id", score: 123 },
+    #       { acq_id: "rql:acq:process_id/thread_id", score: 456 },
+    #     ] # ordered set (by score) with information about an acquier and their position in queue
+    #   }
+    #
+    # @api private
+    # @since 0.1.0
+    def queue_info(redis_client, lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+
+      result = redis_client.pipelined do |pipeline|
+        pipeline.call('EXISTS', lock_key_queue)
+        pipeline.call('ZRANGE', lock_key_queue, '0', '-1', 'WITHSCORES')
+      end
+
+      exists_cmd_res = result[0]
+      zrange_cmd_res = result[1]
+
+      if exists_cmd_res == 1
+        # NOTE: queue existed during the piepline invocation
+        {
+          lock_queue: lock_key_queue,
+          queue: zrange_cmd_res.map { |val| { acq_id: val[0], score: val[1] } }
+        }
+      else
+        # NOTE: queue did not exist during the pipeline invocation
+        nil
+      end
+    end
+
     private
 
     # @param timeout [NilClass,Integer]

data/lib/redis_queued_locks/client.rb

@@ -2,6 +2,7 @@
 
 # @api public
 # @since 0.1.0
+# rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @since 0.1.0
   include Qonfig::Configurable
@@ -154,6 +155,42 @@ class RedisQueuedLocks::Client
     )
   end
 
+  # @param lock_name [String]
+  # @return [Boolean]
+  #
+  # @api public
+  # @since 0.1.0
+  def locked?(lock_name)
+    RedisQueuedLocks::Acquier.locked?(redis_client, lock_name)
+  end
+
+  # @param lock_name [String]
+  # @return [Boolean]
+  #
+  # @api public
+  # @since 0.1.0
+  def queued?(lock_name)
+    RedisQueuedLocks::Acquier.queued?(redis_client, lock_name)
+  end
+
+  # @param lock_name [String]
+  # @return [Hash,NilClass]
+  #
+  # @api public
+  # @since 0.1.0
+  def lock_info(lock_name)
+    RedisQueuedLocks::Acquier.lock_info(redis_client, lock_name)
+  end
+
+  # @param lock_name [String]
+  # @return [Hash,NilClass]
+  #
+  # @api public
+  # @since 0.1.0
+  def queue_info(lock_name)
+    RedisQueuedLocks::Acquier.queue_info(redis_client, lock_name)
+  end
+
   # @option batch_size [Integer]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
   #
@@ -167,3 +204,4 @@ class RedisQueuedLocks::Client
     )
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/version.rb

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

data/redis_queued_locks.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.email   = ['iamdaiver@gmail.com']
 
   spec.summary     = 'Queued distributed locks based on Redis.'
-  spec.description = 'Distributed lock implementation with "lock acquisition queue" ' \
+  spec.description = 'Distributed locks with "lock acquisition queue" ' \
                      'capabilities based on the Redis Database.'
   spec.homepage    = 'https://github.com/0exp/redis_queued_locks'
   spec.license     = 'MIT'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-26 00:00:00.000000000 Z
+date: 2024-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.28'
-description: Distributed lock implementation with "lock acquisition queue" capabilities
-  based on the Redis Database.
+description: Distributed locks with "lock acquisition queue" capabilities based on
+  the Redis Database.
 email:
 - iamdaiver@gmail.com
 executables: []