futex 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e89a9a954b7117d46792c48cbd5b5c123a33050321266028f70bd2fd3df0702a
-  data.tar.gz: 4bc7abbb6b455e073bc9fb0c5f69612ce2bcc5fc9c09e2fdf651d57af5b551a5
+  metadata.gz: b6b80bd02f4bb99bf83264c534c6c9f13265e11acd484cb389f75fbfbc809650
+  data.tar.gz: a599ea5bd0024323fbaed93313985e424b16c8d2468a44809e2626281c1b86ff
 SHA512:
-  metadata.gz: f96770a733ecc3661551ddb1d99b9098610176236a06c8dcb7001f8dce2476f28cabc58f2ac1b2ff7eb4bbb061e6fb0885b3b63711f7165c14273cb283601b5c
-  data.tar.gz: 6a9700fef33eebaceae3caa7d07d0f7fa494a2b0cfc02187ffd5362b79bf0dd4c74c3a70d2bac8cc90e44350f73dc0c0b69992f62510d7b349e5011ce790e8a4
+  metadata.gz: 3d2fd4b4c45ac7d182e76c3f32bc727554fb426198c18d6483d80f8eb954d6a2e233f26032a1b3cbddc1c412ec2b5cb927bcbd727f40b7c1134b7f12ab961485
+  data.tar.gz: cacd448755258045d862c633bab834440f80f21c5a37f9d341241b464f8a8f10f7643ac82d8a68969251c647ce12af78bd799e7a251407095b058bea300f09d3

data/futex.gemspec

@@ -31,7 +31,7 @@ Gem::Specification.new do |s|
   s.rubygems_version = '2.3.3'
   s.required_ruby_version = '>=2.3'
   s.name = 'futex'
-  s.version = '0.6.3'
+  s.version = '0.7.0'
   s.license = 'MIT'
   s.summary = 'File-based mutex'
   s.description = 'Ruby Gem for file-based locking'

data/lib/futex.rb

@@ -34,7 +34,8 @@ require 'time'
 #  end
 #
 # The file <tt>/tmp/my-file.txt.lock<tt> will be created and
-# used as an entrance lock.
+# used as an entrance lock. If the file is already locked by another thread
+# or another process, exception <tt>Futex::CantLock</tt> will be raised.
 #
 # If you are not planning to write to the file, to speed things up, you may
 # want to get a non-exclusive access to it, by providing <tt>false</tt> to
@@ -52,6 +53,10 @@ require 'time'
 # Copyright:: Copyright (c) 2018 Yegor Bugayenko
 # License:: MIT
 class Futex
+  # Exception that is raised when we can't lock because of some other
+  # process that is holding the lock now.
+  class CantLock < StandardError; end
+
   # Creates a new instance of the class.
   def initialize(path, log: STDOUT, timeout: 16, sleep: 0.005,
     lock: path + '.lock', logging: false)
@@ -63,7 +68,17 @@ class Futex
     @lock = lock
   end
 
-  # Open the file.
+  # Open the file. By default the file will be locked for exclusive access,
+  # which means that absolutely no other process will be able to do the same.
+  # This type of access (exclusive) is supposed to be used when you are
+  # making changes to the file. However, very often you may need just to
+  # read it and it's OK to let many processes do the reading at the same time,
+  # provided none of them do the writing. In that case you should call this
+  # method <tt>open()</tt> with <tt>false</tt> first argument, which will mean
+  # "shared" access. Many threads and processes may have shared access to the
+  # same lock file, but they all will stop and wait if one of them will require
+  # an "exclusive" access. This mechanism is inherited from POSIX, read about
+  # it <a href="http://man7.org/linux/man-pages/man2/flock.2.html">here</a>.
   def open(exclusive = true)
     FileUtils.mkdir_p(File.dirname(@lock))
     step = (1 / @sleep).to_i
@@ -85,7 +100,7 @@ class Futex
         Thread.current.thread_variable_set(:futex_cycle, cycle)
         Thread.current.thread_variable_set(:futex_time, Time.now - start)
         if Time.now - start > @timeout
-          raise "#{b} can't get #{prefix}exclusive access \
+          raise CantLock, "#{b} can't get #{prefix}exclusive access \
 to the file #{@path} because of the lock at #{@lock}, after #{age(start)} \
 of waiting: #{IO.read(@lock)} (modified #{age(File.mtime(@lock))} ago)"
         end

data/test/test_futex.rb

@@ -83,7 +83,7 @@ class FutexTest < Minitest::Test
         end
       end
       sleep 0.1
-      ex = assert_raises do
+      ex = assert_raises(Futex::CantLock) do
         Futex.new(path, timeout: 0.1).open do |f|
           # Will never reach this point
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: futex
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Yegor Bugayenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2018-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest