philiprehberger-lock_kit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea17573729655a3a771771a4491e4ad67313ccdd8c1910964efc84e28cc55cd1
-  data.tar.gz: 3d045b798cd8f8b4df88af8127d4fb1ecd30c0ba252a1058fc90095fc4b98b75
+  metadata.gz: c73f047a2d1e5c9452f0c9ee35ea25f7129211c150c37e81ab8d64685a1e4335
+  data.tar.gz: 037df68b9cdbeffa96ed4a7a356bbed7df5ec0038f82421095c221c2f8937151
 SHA512:
-  metadata.gz: '08161efb6474fd3cc5b04d6896200df0e6c3e638e7eb89e898e2de4e0efee4ab2ac7decf99eea5f472a78c2914bbb1d5e4665e4d80a4fd7d72efdb3d4c942505'
-  data.tar.gz: 1776595c803f9c9285afc8bb6b7fc9f26cf32db45f1067a5f6084d585f741b5c27d6bce6ab2d1824c2db4941991e44bd1c0ac53e71f845e4011ac079b4f5f4af
+  metadata.gz: 86041b9199af015a6a6be088a589447d8bf53d60d47daf3f16d1ec4a98541c858fb85f6d3b09772fad2150793dd215b1f2955db62f7184d2bbbb9c76bf2b94a0
+  data.tar.gz: e6524a26607e7c72305bcb462d038fe2897c9511646ac9ba9dc29ac35d4e8954950f95c113dab0e18615d9d5be07a01f292b429ae509e5f6c6731adda6d43d8c

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-07
+
+### Added
+- `LockKit.age(path)` — returns the age in seconds of an active lock based on its `acquired_at` metadata, or `nil` if not locked or metadata is missing.
+
+## [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

data/README.md

@@ -114,6 +114,14 @@ info = Philiprehberger::LockKit.owner('/tmp/my.lock')
 # => { pid: 12345, hostname: 'web-01', acquired_at: 2026-03-28 12:00:00 +0000 }
 ```
 
+### Lock Age
+
+```ruby
+# Returns the age in seconds (Float) of an active lock, or nil if not locked
+Philiprehberger::LockKit.age('/tmp/my.lock')
+# => 12.34
+```
+
 ### Lock Waiting with Callbacks
 
 ```ruby
@@ -173,7 +181,9 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | `.stale?(pid_file)` | Check if a PID file references a dead process |
 | `.expired?(path)` | Check if a lock has expired based on its TTL |
 | `.owner(path)` | Get lock owner metadata (pid, hostname, acquired_at) |
+| `.age(path)` | Age in seconds of an active lock, or nil if not locked |
 | `.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`
 
@@ -208,6 +218,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.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/lock_kit.rb

@@ -126,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
@@ -218,6 +226,17 @@ module Philiprehberger
       nil
     end
 
+    # Get the age in seconds of an active lock based on its `acquired_at` metadata
+    #
+    # @param path [String] path to the lock file or PID file
+    # @return [Float, nil] age in seconds, or nil if not locked or `acquired_at` is missing
+    def self.age(path)
+      data = owner(path)
+      return nil unless data && data[:acquired_at]
+
+      Time.now - data[:acquired_at]
+    end
+
     # Force break a lock
     #
     # @param path [String] path to the lock file or PID file

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-lock_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-05-07 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.