philiprehberger-lock_kit 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f488799f249ab60e5a0c52ac65dc96904e5523c1a3b2457dcc61ebb337ded57
-  data.tar.gz: 9e90d6aecf73b008c12fb0feb2f650a405ee5da4d2f692a4a5284c2c64b12272
+  metadata.gz: c9a963709d5941abac8fdbbb3c6fe9cf95505b182683a0156d72b31cd1f5bcd7
+  data.tar.gz: d75615d7d5009c958771c6c27defb306727fe937832a1320d233c2c890440fc7
 SHA512:
-  metadata.gz: fb950e220fdd792639a64d35d4950c5e55010969b61fa538881015879fc96610f14578bef5704298f12b0721e401f0e6525a72b8fdae7fff18812384d059acdb
-  data.tar.gz: 7dcb4a028573c4497343df49c62983747b53cdb3e608f3053fef5516dc4f9e59c3d2f03217d27fd448c07975bd5b6a3d74a9bed6dca40c92f0ffe12ee9f90f1e
+  metadata.gz: 2bee02f21982407cee48091a6af645609e9ea19985f11a452eaa700eacc3ca362c0fed2710980a675fc7c67c0d46c33a18fd91bfea75036fb19ce52f30e7738d
+  data.tar.gz: 4cfdd43296b2de0c60b78ca6e96336607d2c84cfce5088ee161888680e30309aa53d1d33cc498e2d571f4d416f7c2bbdc1a5a2eeee60ec90881bced4d53f5d53

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+### Added
+- `LockKit.owner(path)` for inspecting lock holder metadata (PID, hostname, timestamp)
+- `auto_cleanup:` option for automatic stale lock removal
+- `LockKit.with_read_lock` and `LockKit.with_write_lock` for shared/exclusive locking
+- `on_wait:` callback option for monitoring lock contention
+- `LockKit.break!(path, force:)` for manual lock recovery
+
 ## [0.1.1] - 2026-03-26
 
 ### Added

data/README.md

@@ -2,10 +2,14 @@
 
 [![Tests](https://github.com/philiprehberger/rb-lock-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-lock-kit/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-lock_kit.svg)](https://rubygems.org/gems/philiprehberger-lock_kit)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-lock-kit)](https://github.com/philiprehberger/rb-lock-kit/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-lock-kit)](https://github.com/philiprehberger/rb-lock-kit/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-lock-kit)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-lock-kit/bug)](https://github.com/philiprehberger/rb-lock-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-lock-kit/enhancement)](https://github.com/philiprehberger/rb-lock-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
 [![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
-File-based and PID locking for process coordination
+File-based and PID locking for process coordination with stale lock detection, read-write locks, and lock owner identification.
 
 ## Requirements
 
@@ -16,7 +20,7 @@ File-based and PID locking for process coordination
 Add to your Gemfile:
 
 ```ruby
-gem "philiprehberger-lock_kit"
+gem 'philiprehberger-lock_kit'
 ```
 
 Or install directly:
@@ -28,9 +32,9 @@ gem install philiprehberger-lock_kit
 ## Usage
 
 ```ruby
-require "philiprehberger/lock_kit"
+require 'philiprehberger/lock_kit'
 
-Philiprehberger::LockKit.with_file_lock("/tmp/my.lock") do
+Philiprehberger::LockKit.with_file_lock('/tmp/my.lock') do
   # exclusive work here
 end
 ```
@@ -38,7 +42,7 @@ end
 ### File Locking with Timeout
 
 ```ruby
-Philiprehberger::LockKit.with_file_lock("/tmp/my.lock", timeout: 5) do
+Philiprehberger::LockKit.with_file_lock('/tmp/my.lock', timeout: 5) do
   # waits up to 5 seconds for the lock
 end
 ```
@@ -46,15 +50,67 @@ end
 ### PID File Locking
 
 ```ruby
-Philiprehberger::LockKit.with_pid_lock("my_worker") do
+Philiprehberger::LockKit.with_pid_lock('my_worker') do
   # only one process with this name can run at a time
 end
 ```
 
+### Read-Write Locks
+
+```ruby
+# Multiple readers can hold the lock concurrently
+Philiprehberger::LockKit.with_read_lock('/tmp/data.lock', timeout: 5) do
+  # read shared data
+end
+
+# Write lock is exclusive — no readers or other writers allowed
+Philiprehberger::LockKit.with_write_lock('/tmp/data.lock', timeout: 5) do
+  # write shared data
+end
+```
+
+### Automatic Stale Lock Cleanup
+
+```ruby
+Philiprehberger::LockKit.with_file_lock('/tmp/my.lock', auto_cleanup: true) do
+  # automatically removes stale locks from dead processes
+end
+
+Philiprehberger::LockKit.with_pid_lock('my_worker', auto_cleanup: true) do
+  # same for PID locks
+end
+```
+
+### Lock Owner Identification
+
+```ruby
+info = Philiprehberger::LockKit.owner('/tmp/my.lock')
+# => { pid: 12345, hostname: 'web-01', acquired_at: 2026-03-28 12:00:00 +0000 }
+```
+
+### Lock Waiting with Callbacks
+
+```ruby
+Philiprehberger::LockKit.with_file_lock('/tmp/my.lock', timeout: 10, on_wait: ->(elapsed) { puts "Waiting #{elapsed}s..." }) do
+  # callback fires every 0.5s while waiting
+end
+```
+
+### Force Break Lock
+
+```ruby
+# Break stale locks only (raises if held by a live process)
+Philiprehberger::LockKit.break!('/tmp/my.lock')
+# => { broken: true, previous_owner: { pid: 12345, hostname: 'web-01', acquired_at: ... } }
+
+# Force break any lock regardless of status
+Philiprehberger::LockKit.break!('/tmp/my.lock', force: true)
+```
+
 ### Manual File Lock
 
 ```ruby
-lock = Philiprehberger::LockKit::FileLock.new("/tmp/my.lock")
+lock = Philiprehberger::LockKit::FileLock.new('/tmp/my.lock')
 lock.acquire(timeout: 10)
 # ... do work ...
 lock.release
@@ -63,7 +119,7 @@ lock.release
 ### Manual PID Lock
 
 ```ruby
-lock = Philiprehberger::LockKit::PidLock.new("my_worker", dir: "/var/run")
+lock = Philiprehberger::LockKit::PidLock.new('my_worker', dir: '/var/run')
 lock.acquire
 # ... do work ...
 lock.release
@@ -72,8 +128,8 @@ lock.release
 ### Checking Lock Status
 
 ```ruby
-Philiprehberger::LockKit.locked?("/tmp/my.lock")    # => true/false
-Philiprehberger::LockKit.stale?("/tmp/my_worker.pid") # => true/false
+Philiprehberger::LockKit.locked?('/tmp/my.lock')      # => true/false
+Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 ```
 
 ## API
@@ -82,29 +138,46 @@ Philiprehberger::LockKit.stale?("/tmp/my_worker.pid") # => true/false
 
 | Method | Description |
 |--------|-------------|
-| `.with_file_lock(path, timeout: nil) { }` | Execute block with exclusive file lock |
-| `.with_pid_lock(name, dir: Dir.tmpdir) { }` | Execute block with PID file lock |
+| `.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil) { }` | Execute block with exclusive file lock |
+| `.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false) { }` | 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 |
 | `.locked?(path)` | Check if a file is currently locked |
 | `.stale?(pid_file)` | Check if a PID file references a dead process |
+| `.owner(path)` | Get lock owner metadata (pid, hostname, acquired_at) |
+| `.break!(path, force: false)` | Break a lock (stale only by default, any with force) |
 
 ### `LockKit::FileLock`
 
 | Method | Description |
 |--------|-------------|
 | `.new(path)` | Create a file lock instance |
-| `#acquire(timeout: nil)` | Acquire exclusive lock, optional timeout in seconds |
+| `#acquire(timeout: nil, auto_cleanup: false, on_wait: nil)` | Acquire exclusive lock with optional timeout, cleanup, and wait callback |
 | `#release` | Release the lock and close the file handle |
 | `#locked?` | Check if the file is currently locked |
+| `#owner` | Get lock owner metadata |
 
 ### `LockKit::PidLock`
 
 | Method | Description |
 |--------|-------------|
 | `.new(name, dir: Dir.tmpdir)` | Create a PID lock instance |
-| `#acquire` | Acquire PID lock, raises if held by a living process |
+| `#acquire(auto_cleanup: false)` | Acquire PID lock, raises if held by a living process |
 | `#release` | Release lock and remove PID file |
 | `#locked?` | Check if lock is held by a living process |
 | `#stale?` | Check if PID file references a dead process |
+| `#owner` | Get lock owner metadata |
+
+### `LockKit::ReadWriteLock`
+
+| Method | Description |
+|--------|-------------|
+| `.new(path)` | Create a read-write lock instance |
+| `#acquire_read(timeout: nil)` | Acquire shared read lock |
+| `#release_read` | Release the read lock |
+| `#acquire_write(timeout: nil)` | Acquire exclusive write lock |
+| `#release_write` | Release the write lock |
+| `#reader_count` | Get current number of active readers |
 
 ## Development
 
@@ -114,6 +187,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
 [MIT](LICENSE)

data/lib/philiprehberger/lock_kit/file_lock.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'socket'
+
 module Philiprehberger
   module LockKit
     # Exclusive file lock using flock(2)
@@ -10,15 +13,22 @@ module Philiprehberger
       # @param path [String] path to the lock file
       def initialize(path)
         @path = path
+        @meta_path = "#{path}.meta"
         @file = nil
       end
 
       # Acquire an exclusive lock on the file
       #
       # @param timeout [Numeric, nil] seconds to wait before raising; nil means non-blocking single attempt
+      # @param auto_cleanup [Boolean] when true, check for stale locks and remove them
+      # @param on_wait [Proc, nil] callback invoked every 0.5s while waiting; receives elapsed seconds
       # @return [true] when the lock is acquired
       # @raise [LockKit::Error] if the lock cannot be acquired
-      def acquire(timeout: nil)
+      def acquire(timeout: nil, auto_cleanup: false, on_wait: nil)
+        if auto_cleanup
+          cleanup_stale_lock
+        end
+
         @file = File.open(@path, File::CREAT | File::RDWR)
 
         if timeout.nil?
@@ -28,18 +38,29 @@ module Philiprehberger
           end
         else
           deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          last_callback = start_time
 
           until @file.flock(File::LOCK_EX | File::LOCK_NB)
-            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            remaining = deadline - now
+
             if remaining <= 0
               close_file
               raise Error, "Timeout acquiring lock on #{@path} after #{timeout}s"
             end
 
+            if on_wait && (now - last_callback) >= 0.5
+              elapsed = (now - start_time).round(1)
+              on_wait.call(elapsed)
+              last_callback = now
+            end
+
             sleep [0.05, remaining].min
           end
         end
 
+        write_metadata
         true
       end
 
@@ -49,6 +70,7 @@ module Philiprehberger
       def release
         return unless @file
 
+        remove_metadata
         @file.flock(File::LOCK_UN)
         close_file
       end
@@ -74,8 +96,71 @@ module Philiprehberger
         end
       end
 
+      # Read lock owner metadata
+      #
+      # @return [Hash, nil] hash with :pid, :hostname, :acquired_at keys or nil
+      def owner
+        return nil unless File.exist?(@meta_path)
+
+        content = File.read(@meta_path).strip
+        return nil if content.empty?
+
+        data = JSON.parse(content)
+        {
+          pid: data['pid'],
+          hostname: data['hostname'],
+          acquired_at: data['acquired_at'] ? Time.parse(data['acquired_at']) : nil
+        }
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
       private
 
+      def write_metadata
+        metadata = {
+          'pid' => Process.pid,
+          'hostname' => Socket.gethostname,
+          'acquired_at' => Time.now.iso8601
+        }
+        File.write(@meta_path, JSON.generate(metadata))
+      end
+
+      def remove_metadata
+        FileUtils.rm_f(@meta_path)
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def cleanup_stale_lock
+        return unless File.exist?(@path)
+
+        meta_path = "#{@path}.meta"
+        return unless File.exist?(meta_path)
+
+        content = File.read(meta_path).strip
+        return if content.empty?
+
+        data = JSON.parse(content)
+        pid = data['pid']
+        return unless pid
+
+        unless process_alive?(pid)
+          FileUtils.rm_f(meta_path)
+        end
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+
       def close_file
         @file&.close
         @file = nil

data/lib/philiprehberger/lock_kit/pid_lock.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'socket'
 require 'tmpdir'
 
 module Philiprehberger
   module LockKit
     # PID-file based lock with stale process detection
     #
-    # Writes the current process ID to a file. Other processes can check the
-    # file to determine if the lock holder is still alive, enabling automatic
-    # recovery from crashed processes.
+    # Writes the current process ID, hostname, and timestamp to a file in JSON
+    # format. Other processes can check the file to determine if the lock holder
+    # is still alive, enabling automatic recovery from crashed processes.
     class PidLock
       # @param name [String] lock name (used as the PID file basename)
       # @param dir [String] directory for the PID file (defaults to system tmpdir)
@@ -21,13 +23,15 @@ module Philiprehberger
 
       # Acquire the PID lock
       #
-      # Creates a PID file containing the current process ID. If a PID file
-      # already exists, checks whether the owning process is still alive. Stale
-      # PID files from dead processes are automatically cleaned up.
+      # Creates a PID file containing metadata (PID, hostname, timestamp) in
+      # JSON format. If a PID file already exists, checks whether the owning
+      # process is still alive. Stale PID files from dead processes are
+      # automatically cleaned up.
       #
+      # @param auto_cleanup [Boolean] when true, automatically remove stale locks
       # @return [true] when the lock is acquired
       # @raise [LockKit::Error] if the lock is held by a living process
-      def acquire
+      def acquire(auto_cleanup: false)
         if File.exist?(@pid_path)
           existing_pid = read_pid
 
@@ -39,7 +43,12 @@ module Philiprehberger
           FileUtils.rm_f(@pid_path)
         end
 
-        File.write(@pid_path, Process.pid.to_s)
+        metadata = {
+          'pid' => Process.pid,
+          'hostname' => Socket.gethostname,
+          'acquired_at' => Time.now.iso8601
+        }
+        File.write(@pid_path, JSON.generate(metadata))
         @acquired = true
         true
       end
@@ -81,6 +90,17 @@ module Philiprehberger
         !process_alive?(pid)
       end
 
+      # Read lock owner metadata from the PID file
+      #
+      # @return [Hash, nil] hash with :pid, :hostname, :acquired_at keys or nil
+      def owner
+        return nil unless File.exist?(@pid_path)
+
+        read_metadata
+      rescue Errno::ENOENT
+        nil
+      end
+
       private
 
       # @return [Integer, nil]
@@ -88,11 +108,37 @@ module Philiprehberger
         content = File.read(@pid_path).strip
         return nil if content.empty?
 
+        # Try JSON format first
+        data = JSON.parse(content)
+        data.is_a?(Hash) ? data['pid'] : Integer(data)
+      rescue JSON::ParserError
+        # Fall back to plain PID format for backwards compatibility
         Integer(content)
       rescue ArgumentError, Errno::ENOENT
         nil
       end
 
+      # @return [Hash, nil] parsed metadata with symbolized keys
+      def read_metadata
+        content = File.read(@pid_path).strip
+        return nil if content.empty?
+
+        data = JSON.parse(content)
+        {
+          pid: data['pid'],
+          hostname: data['hostname'],
+          acquired_at: data['acquired_at'] ? Time.parse(data['acquired_at']) : nil
+        }
+      rescue JSON::ParserError
+        # Plain PID format — limited metadata
+        pid = Integer(content, exception: false)
+        return nil unless pid
+
+        { pid: pid, hostname: nil, acquired_at: nil }
+      rescue Errno::ENOENT
+        nil
+      end
+
       # @param pid [Integer]
       # @return [Boolean]
       def process_alive?(pid)

data/lib/philiprehberger/lock_kit/read_write_lock.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module LockKit
+    # Read-write lock supporting shared reads and exclusive writes
+    #
+    # Read locks are shared — multiple readers can hold the lock concurrently.
+    # Write locks are exclusive — no readers or other writers are allowed.
+    # Uses a `.readers` counter file alongside the lock file to track state.
+    class ReadWriteLock
+      # @param path [String] base path for the lock files
+      def initialize(path)
+        @path = path
+        @write_lock_path = "#{path}.write"
+        @readers_path = "#{path}.readers"
+        @write_file = nil
+      end
+
+      # Acquire a shared read lock
+      #
+      # @param timeout [Numeric, nil] seconds to wait before raising
+      # @return [true] when the lock is acquired
+      # @raise [LockKit::Error] if a write lock is held and timeout expires
+      def acquire_read(timeout: nil)
+        deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
+
+        loop do
+          # Check if a write lock is held
+          unless write_locked?
+            increment_readers
+            # Double-check no writer snuck in
+            unless write_locked?
+              return true
+            end
+
+            decrement_readers
+          end
+
+          raise Error, "Could not acquire read lock on #{@path}" unless deadline
+
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            raise Error, "Timeout acquiring read lock on #{@path} after #{timeout}s"
+          end
+
+          sleep [0.05, remaining].min
+        end
+      end
+
+      # Release the shared read lock
+      #
+      # @return [void]
+      def release_read
+        decrement_readers
+      end
+
+      # Acquire an exclusive write lock
+      #
+      # @param timeout [Numeric, nil] seconds to wait before raising
+      # @return [true] when the lock is acquired
+      # @raise [LockKit::Error] if the lock cannot be acquired
+      def acquire_write(timeout: nil)
+        @write_file = File.open(@write_lock_path, File::CREAT | File::RDWR)
+        deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
+
+        # First, acquire the write file lock
+        loop do
+          break if @write_file.flock(File::LOCK_EX | File::LOCK_NB)
+
+          if deadline
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              close_write_file
+              raise Error, "Timeout acquiring write lock on #{@path} after #{timeout}s"
+            end
+
+            sleep [0.05, remaining].min
+          else
+            close_write_file
+            raise Error, "Could not acquire write lock on #{@path}"
+          end
+        end
+
+        # Then, wait for all readers to finish
+        loop do
+          break if reader_count.zero?
+
+          if deadline
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              @write_file.flock(File::LOCK_UN)
+              close_write_file
+              raise Error, "Timeout acquiring write lock on #{@path} after #{timeout}s — readers still active"
+            end
+
+            sleep [0.05, remaining].min
+          else
+            @write_file.flock(File::LOCK_UN)
+            close_write_file
+            raise Error, "Could not acquire write lock on #{@path} — readers still active"
+          end
+        end
+
+        true
+      end
+
+      # Release the exclusive write lock
+      #
+      # @return [void]
+      def release_write
+        return unless @write_file
+
+        @write_file.flock(File::LOCK_UN)
+        close_write_file
+      end
+
+      # Return the current number of active readers
+      #
+      # @return [Integer]
+      def reader_count
+        return 0 unless File.exist?(@readers_path)
+
+        count = File.read(@readers_path).strip.to_i
+        count.negative? ? 0 : count
+      rescue Errno::ENOENT
+        0
+      end
+
+      private
+
+      def write_locked?
+        return false unless File.exist?(@write_lock_path)
+
+        f = File.open(@write_lock_path, File::CREAT | File::RDWR)
+        got_lock = f.flock(File::LOCK_EX | File::LOCK_NB)
+        if got_lock
+          f.flock(File::LOCK_UN)
+          f.close
+          false
+        else
+          f.close
+          true
+        end
+      end
+
+      def increment_readers
+        update_reader_count(1)
+      end
+
+      def decrement_readers
+        update_reader_count(-1)
+      end
+
+      def update_reader_count(delta)
+        lock_path = "#{@readers_path}.lock"
+        File.open(lock_path, File::CREAT | File::RDWR) do |f|
+          f.flock(File::LOCK_EX)
+          current = begin
+            File.read(@readers_path).strip.to_i
+          rescue Errno::ENOENT
+            0
+          end
+          new_count = [current + delta, 0].max
+          File.write(@readers_path, new_count.to_s)
+          f.flock(File::LOCK_UN)
+        end
+      end
+
+      def close_write_file
+        @write_file&.close
+        @write_file = nil
+      end
+    end
+  end
+end

data/lib/philiprehberger/lock_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module LockKit
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/lock_kit.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require 'time'
+
 require_relative 'lock_kit/version'
 require_relative 'lock_kit/file_lock'
 require_relative 'lock_kit/pid_lock'
+require_relative 'lock_kit/read_write_lock'
 
 module Philiprehberger
   module LockKit
@@ -12,12 +15,14 @@ module Philiprehberger
     #
     # @param path [String] path to the lock file
     # @param timeout [Numeric, nil] seconds to wait before raising
+    # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
+    # @param on_wait [Proc, nil] callback invoked every 0.5s while waiting; receives elapsed seconds
     # @yield block to execute while the lock is held
     # @return [Object] the return value of the block
     # @raise [Error] if the lock cannot be acquired
-    def self.with_file_lock(path, timeout: nil, &block)
+    def self.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil, &block)
       lock = FileLock.new(path)
-      lock.acquire(timeout: timeout)
+      lock.acquire(timeout: timeout, auto_cleanup: auto_cleanup, on_wait: on_wait)
       begin
         block.call
       ensure
@@ -29,12 +34,13 @@ module Philiprehberger
     #
     # @param name [String] lock name
     # @param dir [String] directory for the PID file
+    # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
     # @yield block to execute while the lock is held
     # @return [Object] the return value of the block
     # @raise [Error] if the lock is held by another process
-    def self.with_pid_lock(name, dir: Dir.tmpdir, &block)
+    def self.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false, &block)
       lock = PidLock.new(name, dir: dir)
-      lock.acquire
+      lock.acquire(auto_cleanup: auto_cleanup)
       begin
         block.call
       ensure
@@ -42,6 +48,45 @@ module Philiprehberger
       end
     end
 
+    # Execute a block while holding a shared read lock
+    #
+    # Multiple readers can hold the lock concurrently. Blocks if a write lock
+    # is held.
+    #
+    # @param path [String] base path for the lock files
+    # @param timeout [Numeric, nil] seconds to wait before raising
+    # @yield block to execute while the read lock is held
+    # @return [Object] the return value of the block
+    # @raise [Error] if the lock cannot be acquired
+    def self.with_read_lock(path, timeout: nil, &block)
+      lock = ReadWriteLock.new(path)
+      lock.acquire_read(timeout: timeout)
+      begin
+        block.call
+      ensure
+        lock.release_read
+      end
+    end
+
+    # Execute a block while holding an exclusive write lock
+    #
+    # No readers or other writers are allowed while the write lock is held.
+    #
+    # @param path [String] base path for the lock files
+    # @param timeout [Numeric, nil] seconds to wait before raising
+    # @yield block to execute while the write lock is held
+    # @return [Object] the return value of the block
+    # @raise [Error] if the lock cannot be acquired
+    def self.with_write_lock(path, timeout: nil, &block)
+      lock = ReadWriteLock.new(path)
+      lock.acquire_write(timeout: timeout)
+      begin
+        block.call
+      ensure
+        lock.release_write
+      end
+    end
+
     # Check if a file is currently locked by another process
     #
     # @param path [String] path to the lock file
@@ -60,7 +105,14 @@ module Philiprehberger
       content = File.read(pid_file).strip
       return true if content.empty?
 
-      pid = Integer(content)
+      # Try JSON format first
+      pid = begin
+        data = JSON.parse(content)
+        data.is_a?(Hash) ? data['pid'] : Integer(data)
+      rescue JSON::ParserError
+        Integer(content)
+      end
+
       Process.kill(0, pid)
       false
     rescue ArgumentError
@@ -70,5 +122,85 @@ module Philiprehberger
     rescue Errno::EPERM
       false
     end
+
+    # Get lock owner metadata
+    #
+    # @param path [String] path to the lock file or PID file
+    # @return [Hash, nil] hash with :pid, :hostname, :acquired_at keys or nil if not locked
+    def self.owner(path)
+      # Check for file lock metadata
+      meta_path = "#{path}.meta"
+      if File.exist?(meta_path)
+        content = File.read(meta_path).strip
+        unless content.empty?
+          data = JSON.parse(content)
+          return {
+            pid: data['pid'],
+            hostname: data['hostname'],
+            acquired_at: data['acquired_at'] ? Time.parse(data['acquired_at']) : nil
+          }
+        end
+      end
+
+      # Check for PID lock (JSON format)
+      if File.exist?(path)
+        content = File.read(path).strip
+        unless content.empty?
+          data = JSON.parse(content)
+          return {
+            pid: data['pid'],
+            hostname: data['hostname'],
+            acquired_at: data['acquired_at'] ? Time.parse(data['acquired_at']) : nil
+          }
+        end
+      end
+
+      nil
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    # Force break a lock
+    #
+    # @param path [String] path to the lock file or PID file
+    # @param force [Boolean] when true, break any lock regardless of PID status
+    # @return [Hash] result with :broken and :previous_owner or :reason keys
+    # @raise [Error] if the lock is held by a live process and force is false
+    def self.break!(path, force: false)
+      meta_path = "#{path}.meta"
+
+      # Determine the previous owner
+      previous_owner = owner(path)
+
+      unless previous_owner || File.exist?(path)
+        return { broken: false, reason: 'not locked' }
+      end
+
+      # Check if the lock holder is alive
+      if previous_owner && previous_owner[:pid]
+        alive = begin
+          Process.kill(0, previous_owner[:pid])
+          true
+        rescue Errno::ESRCH
+          false
+        rescue Errno::EPERM
+          true
+        end
+
+        if alive && !force
+          raise Error, "Lock on #{path} is held by living process #{previous_owner[:pid]}"
+        end
+      end
+
+      # Break the lock
+      FileUtils.rm_f(path)
+      FileUtils.rm_f(meta_path)
+
+      if previous_owner
+        { broken: true, previous_owner: previous_owner }
+      else
+        { broken: true, previous_owner: nil }
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-lock_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-29 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.
@@ -24,6 +24,7 @@ files:
 - lib/philiprehberger/lock_kit.rb
 - lib/philiprehberger/lock_kit/file_lock.rb
 - lib/philiprehberger/lock_kit/pid_lock.rb
+- lib/philiprehberger/lock_kit/read_write_lock.rb
 - lib/philiprehberger/lock_kit/version.rb
 homepage: https://github.com/philiprehberger/rb-lock-kit
 licenses: