philiprehberger-lock_kit 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f82a00dac3cb9f7457b0d6e98d97a14a86502b1d2b2fe688b5bef0c07dcdbda1
-  data.tar.gz: 88e1f0ac7f71c7585e7730b3984a9d4646c63ec7324f23731d2c088806257a3a
+  metadata.gz: fd5f40b2057061170fc5913d9ac238f7070d3fb05025e9f5bffe2e321e3b240b
+  data.tar.gz: ece6023899b7329973758c48b3f7da96937e9cdc700ec4a11f0e572a7f9d4246
 SHA512:
-  metadata.gz: ba54abec814f3c18e17f0942f6954b3d108f59ea302ab8ae82efa21afaf118d911b9cc1c6ad1b089ad15b89faacb1c586372cf0b85ac5fe9a2843c4d89ce5f19
-  data.tar.gz: 45248d0994c40fb782df7ce7185992c7a440267ad7fbc5bd43a27d2b0dc18b10172885b4b4c86aa9ddad550993a1ca661a43f979b7338d289fa0feffe128c5a9
+  metadata.gz: 1b57abbeb1216f641fbe8d386425df778fd50a9aadc64be51f98df41e3f47409e6886c0bfe588cde71223b73a684c7da5c7e4c14996c30e66f70961d0fd8bec3
+  data.tar.gz: 4e85ef77b8c6c6bdb50f327a8ddf0841f19754e40ec20b1cfa52e69b7b5ef1127cf8426ed4c4f5e4584c2ff3e54bc13ed8905ab6cd5a15b68da83d7925966d81

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-21
+
+### Added
+- `ReadWriteLock#write_locked?` promoted to a public non-blocking query method
+- `ReadWriteLock#stats` returning `{ readers:, write_locked: }` snapshot
+- `LockKit.rw_stats(path)` module-level helper for the same snapshot without an instance
+
+## [0.4.0] - 2026-04-15
+
+### Added
+- `with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil)` module method for lock acquisition with exponential backoff retries
+
 ## [0.3.0] - 2026-04-10
 
 ### Added

data/README.md

@@ -64,6 +64,20 @@ Philiprehberger::LockKit.with_write_lock('/tmp/data.lock', timeout: 5) do
 end
 ```
 
+### Retry Lock
+
+```ruby
+# Retries lock acquisition with exponential backoff
+Philiprehberger::LockKit.with_retry_lock('/tmp/my.lock', retries: 5, delay: 0.2, backoff: 2) do
+  # acquired after retrying if initially contended
+end
+
+# With timeout per attempt, TTL, and custom cleanup
+Philiprehberger::LockKit.with_retry_lock('/tmp/my.lock', retries: 3, delay: 0.1, backoff: 2, timeout: 5, ttl: 30) do
+  # each attempt waits up to 5s; lock expires after 30s
+end
+```
+
 ### Lock with TTL (Time-to-Live)
 
 ```ruby
@@ -151,6 +165,7 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | Method | Description |
 |--------|-------------|
 | `.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil, ttl: nil) { }` | Execute block with exclusive file lock |
+| `.with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil) { }` | Execute block with file lock, retrying with exponential backoff |
 | `.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false, ttl: nil) { }` | Execute block with PID file lock |
 | `.with_read_lock(path, timeout: nil) { }` | Execute block with shared read lock |
 | `.with_write_lock(path, timeout: nil) { }` | Execute block with exclusive write lock |
@@ -159,6 +174,7 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | `.expired?(path)` | Check if a lock has expired based on its TTL |
 | `.owner(path)` | Get lock owner metadata (pid, hostname, acquired_at) |
 | `.break!(path, force: false)` | Break a lock (stale only by default, any with force) |
+| `.rw_stats(path)` | Snapshot of a read-write lock as `{ readers:, write_locked: }` |
 
 ### `LockKit::FileLock`
 
@@ -193,6 +209,8 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | `#acquire_write(timeout: nil)` | Acquire exclusive write lock |
 | `#release_write` | Release the write lock |
 | `#reader_count` | Get current number of active readers |
+| `#write_locked?` | Non-blocking check for an active write lock |
+| `#stats` | Snapshot as `{ readers:, write_locked: }` |
 
 ## Development
 

data/lib/philiprehberger/lock_kit/read_write_lock.rb

@@ -126,8 +126,9 @@ module Philiprehberger
         0
       end
 
-      private
-
+      # Non-blocking check for whether a write lock is currently held.
+      #
+      # @return [Boolean]
       def write_locked?
         return false unless File.exist?(@write_lock_path)
 
@@ -143,6 +144,13 @@ module Philiprehberger
         end
       end
 
+      # Snapshot of the current lock state: readers and writer presence.
+      #
+      # @return [Hash] `{ readers: Integer, write_locked: Boolean }`
+      def stats
+        { readers: reader_count, write_locked: write_locked? }
+      end
+
       def increment_readers
         update_reader_count(1)
       end

data/lib/philiprehberger/lock_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module LockKit
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/lock_kit.rb

@@ -89,6 +89,35 @@ module Philiprehberger
       end
     end
 
+    # Execute a block with a file lock, retrying with exponential backoff on failure
+    #
+    # @param path [String] path to the lock file
+    # @param retries [Integer] maximum number of attempts
+    # @param delay [Numeric] initial delay in seconds between retries
+    # @param backoff [Numeric] multiplier applied to delay after each failed attempt
+    # @param timeout [Numeric, nil] seconds to wait per acquire attempt
+    # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
+    # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
+    # @yield block to execute while the lock is held
+    # @return [Object] the return value of the block
+    # @raise [Error] if all retry attempts are exhausted
+    def self.with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil, &block)
+      attempts = 0
+      current_delay = delay
+
+      loop do
+        attempts += 1
+        begin
+          return with_file_lock(path, timeout: timeout, auto_cleanup: auto_cleanup, ttl: ttl, &block)
+        rescue Error
+          raise if attempts >= retries
+
+          sleep current_delay
+          current_delay *= backoff
+        end
+      end
+    end
+
     # Check if a file is currently locked by another process
     #
     # @param path [String] path to the lock file
@@ -97,6 +126,14 @@ module Philiprehberger
       FileLock.new(path).locked?
     end
 
+    # Snapshot of read-write lock state for `path` as `{ readers:, write_locked: }`.
+    #
+    # @param path [String] base path used with `with_read_lock` / `with_write_lock`
+    # @return [Hash] `{ readers: Integer, write_locked: Boolean }`
+    def self.rw_stats(path)
+      ReadWriteLock.new(path).stats
+    end
+
     # Check if a PID file references a dead process
     #
     # @param pid_file [String] path to the PID file

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-lock_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-11 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies: []
 description: File locks using flock and PID file locks with stale detection for coordinating
   between processes. Timeout support and automatic cleanup.