safe_flock 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d93a87058706f01d75abc1892f295c1448bbe62829dbd71fd05f50b21660c24
-  data.tar.gz: 50307bf731dcba44c41e0304154cc38e67d8ef3f93e45de02bd7568c05ea12d6
+  metadata.gz: 90677ce98f751bb3855c156aa1850a712213de79ab048b3cb33000dffc023c3a
+  data.tar.gz: 3131f49fd5b0c0f898d3de3e95568ab2d8636034ff4a8aa217d8d02b20cf9716
 SHA512:
-  metadata.gz: 40506d496027784cd008d5ff95fd855e85d84ea492ff2f7be40a84bb3393fdce11be11ecf0a249d820ea953708eb4e3078a596d433ce3313cc47e5b312021002
-  data.tar.gz: 71c2b6401b2e6b93e4172d53b8a93b0fdd6c282c2da976050f7ca5c6923aaf69de94297e48027fe4f23118f57fb7b991a6d9bf1c9723499aa40bec6f7408e2a2
+  metadata.gz: a91c92fe2c33aa5c4b957b78ab9b694da2848f9c4d1f0fca3c74902ee4a96213995a6d32d10ab47f2f7e320c04d7d0c87faf79845853f6ac2cb53eb98fbc6c56
+  data.tar.gz: e499f43feb9b3ceef984c9c05eae963e12c7dbf0a2a4280d38fe7fc6d274dd3cfa173d29fede800323c4e13617a413975d2a1604f920bfbf535cd581a915cee9

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/safe_flock.svg)](http://badge.fury.io/rb/safe_flock) [![Build Status](https://travis-ci.org/starjuice/safe_flock.svg?branch=master)](https://travis-ci.org/starjuice/safe_flock) [![Inline docs](http://inch-ci.org/github/starjuice/safe_flock.svg?branch=master)](http://inch-ci.org/github/starjuice/safe_flock)
+
 # SafeFlock
 
 Thread-safe, transferable, flock-based file lock.
@@ -24,6 +26,10 @@ Or install it yourself as:
 
     $ gem install safe_flock
 
+## Documentation
+
+For documentation of the released gem, see [rubydoc.info](http://www.rubydoc.info/gems/safe_flock).
+
 ## Usage
 
 Simple example:
@@ -41,9 +47,15 @@ The use case for which the helper was created:
 ```
 require "safe_flock"
 
-SafeFlock.create("/var/run/myapp/myapp.lck") do
+SafeFlock.create("/var/run/myapp/myapp.lck") do |lock|
   child = fork do
+
     # ... mutually excluded processing
+
+    lock.unlock
+
+    # ... non-critical processing
+
   end
 end
 Process.detach(child)
@@ -53,6 +65,8 @@ Process.detach(child)
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+To run the test suite, run `bundle exec rake spec`.
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing

data/lib/safe_flock.rb

@@ -1,14 +1,50 @@
 require "safe_flock/lockfile"
 require "safe_flock/version"
 
+##
+# Thread-safe, transferable, flock-based lock file
+#
 module SafeFlock
 
-  class Error < RuntimeError; end
+  ##
+  # Raised when the file can't be locked in time
+  #
   class Locked < RuntimeError; end
 
-  def self.create(path, options = {})
+  ##
+  # Ensure mutual exclusion of a block with +flock+
+  #
+  # * The block is only executed if the lock can be acquired.
+  # * The lock is held for the duration of the block.
+  # * Any child process forked within the block holds the lock
+  #   until it terminates or explicitly releases the lock
+  #   (see SafeFlock::Lockfile#unlock}).
+  # * No other thread may enter the block while the lock is held.
+  # * The lock file _may_ be left in place after the lock is released,
+  #   but this behaviour should not be relied upon.
+  #
+  # @param [String] path
+  #   path of file to flock (created if necessary).
+  #   Absolute pathname (see {Pathname#realpath}) recommended for per-path thread mutex
+  #   and for processes in which the present working directory (see {Dir.chdir}) changes.
+  # @option options [Float] :max_wait
+  #   approximate maximum seconds to wait for the lock.
+  #   A zero +max_wait+ requests a non-blocking attempt
+  #   (i.e. give up immediately if file already locked).
+  #
+  # @return [Object] the value of the block
+  #
+  # @raise [SafeFlock::Locked] if the lock could not be acquired.
+  #   If +max_wait is zero, the file was already locked.
+  #   Otherwise, timed out waiting for the lock.
+  # @raise [Exception] if an IO error occurs opening the lock file
+  #   e.g. +Errno::EACCES+
+  #
+  # TODO implement configurable retry
+  #
+  def self.create(path, max_wait: 5.0)
     raise(ArgumentError, "Block required") unless block_given?
-    lockfile = Lockfile.new(path, options)
+    lockfile = Lockfile.new(path, max_wait: max_wait)
     begin
       if lockfile.lock
         begin

data/lib/safe_flock/lockfile.rb

@@ -2,18 +2,20 @@ require "time"
 
 module SafeFlock
 
+  ##
+  # Thread-safe, transferable, flock-based lock file implementation
+  #
+  # See {SafeFlock.create} for a safe way to wrap the creation, locking and unlocking of the lock file.
+  #
   class Lockfile
 
-    class Error < RuntimeError; end
-    class Locked < RuntimeError; end
-
     @@global_mutex = Mutex.new unless defined?(@@global_mutex)
     @@path_mutex = {} unless defined?(@@path_mutex)
 
-    # +path+ full pathname of mutually agreed lock file.
+    ##
+    # Initialize (but do not lock)
     #
-    # +options+
-    # * +max_wait+ seconds to retry acquiring lock before giving up and raising +Error+ (+5.0+)
+    # See {SafeFlock.create} for a safe way to wrap the creation, locking and unlocking of the lock file.
     #
     def initialize(path, max_wait: 5.0)
       @pid = $$
@@ -25,6 +27,25 @@ module SafeFlock
       @lockfd = nil
     end
 
+    ##
+    # Lock the lock file
+    #
+    # See {SafeFlock.create} for a safe way to wrap the creation, locking and unlocking of the lock file.
+    #
+    # Attempt to {File#flock} the lock file, creating it if necessary.
+    #
+    # If +max_wait+ is zero, the attempt is non-blocking: if the file
+    # is already locked, give up immediately. Otherwise, continue
+    # trying to lock the file for approximately +max_wait+ seconds.
+    #
+    # The operation is performed under a per-path thread mutex to
+    # preserve mutual exclusion across threads.
+    #
+    # @return [true|false] whether the lock was acquired
+    #
+    # @raise [Exception] if an IO error occurs opening the lock file
+    #   e.g. +Errno::EACCES+
+    #
     def lock
       deadline = Time.now.to_f + @max_wait
       while !(is_locked = try_lock)
@@ -37,9 +58,16 @@ module SafeFlock
       is_locked
     end
 
-    # If the lock is inherited by a forked child process, it will hold the lock until
-    # the child calls +unlock+ (or terminates) _and_ the parent's +Lockfile.create+
-    # block terminates. The parent should not call +unlock+.
+    ##
+    # Unlock the lock file
+    #
+    # See {SafeFlock.create} for a safe way to wrap the creation, locking and unlocking of the lock file.
+    #
+    # Unlock the lock file in the current process.
+    #
+    # The only intended use case for this method is in a forked child process that does significant work
+    # after the mutually exclusive work for which it required the lock. In such cases, the process may
+    # call +unlock+ after the mutually exclusive work is complete.
     #
     def unlock
       if @lockfd
@@ -51,21 +79,36 @@ module SafeFlock
       end
     end
 
-    attr_reader :path, :pid, :thread_id
+    ##
+    # The path to the lock file
+    #
+    attr_reader :path
+
+    ##
+    # The process that created the lock file
+    #
+    attr_reader :pid
+
+    ##
+    # A unique identifier for the thread that created the lock file
+    #
+    attr_reader :thread_id
 
     private
 
     def try_lock
+      flocked = false
       begin
         if try_mutex_lock
           @lockfd = File.new(@path, "a")
-          @lockfd.flock(File::LOCK_EX | File::LOCK_NB)
+          flocked = @lockfd.flock(File::LOCK_EX | File::LOCK_NB)
+        end
+      ensure
+        if !flocked
+          @lockfd.close if @lockfd and !@lockfd.closed?
+          @lockfd = nil
+          mutex_unlock
         end
-      rescue
-        @lockfd.close if @lockfd and !@lockfd.closed?
-        @lockfd = nil
-        mutex_unlock
-        raise
       end
     end
 

data/lib/safe_flock/version.rb

@@ -1,3 +1,8 @@
 module SafeFlock
-  VERSION = "0.1.0"
+  ##
+  # Library version
+  #
+  # Semantically versioned, see {https://semver.org/}.
+  #
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safe_flock
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sheldon Hearn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-02 00:00:00.000000000 Z
+date: 2018-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler