futex 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7d43b57ed9b9c1976f33c1da3d39e9646bbb5e890594c339ca7178da830db81
-  data.tar.gz: 7584b99738962f3526367c4310a5a626e8bcec599e5064350825f7a784ab0fac
+  metadata.gz: e19f93d6754a7535a3a7824b2ba55aa6fb8fcf00e63b04011af936865e26895f
+  data.tar.gz: da61f106a45c5da30d76891f88f3adf389c1610c852604326b3d182eadfe1215
 SHA512:
-  metadata.gz: 8af3cb3b44c1e665d0a7744b5321b2084844d1b8c31b73cc37ea1abe47cc6e9c30ace004fd6abac823998a3584385ac18de237bebd53fc6702df186e2646b0bf
-  data.tar.gz: c99a473b9ecf837cfc95d852ce2e5886b492ce19cba9929cc3dbaef70f80d8bccbb182f9ae08006f6e5ae35611af2819ef0ae4532e00670f6c91c75016a52c90
+  metadata.gz: d1adb27a04e721ff4ba1356afd44e19731b7193938b4fba03805eab9722c1b986a20bd4e5f0343de3f685e71b95b0d4e94f34213a49007839fc4243090cc87a0
+  data.tar.gz: 29748f308f7790b67d3e33cf1827bcaea200a2b2a9f7aa977db77f08e289176fc5f65b9927ef5f88309559f59886a414bc12a0988cc0a40a236ba52edc674cc5

data/.rubocop.yml

@@ -2,6 +2,8 @@ AllCops:
   DisplayCopNames: true
   TargetRubyVersion: 2.3.3
 
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 Metrics/AbcSize:

data/.rultor.yml

@@ -20,4 +20,7 @@ architect:
 - yegor256
 merge:
   commanders: []
+  script: |-
+    bundle install
+    rake
 deploy: {}

data/README.md

@@ -1,9 +1,12 @@
+[![EO principles respected here](http://www.elegantobjects.org/badge.svg)](http://www.elegantobjects.org)
 [![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/futex)](http://www.rultor.com/p/yegor256/futex)
 [![We recommend RubyMine](http://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
 
 [![Build Status](https://travis-ci.org/yegor256/futex.svg)](https://travis-ci.org/yegor256/futex)
+[![Build status](https://ci.appveyor.com/api/projects/status/po1mn8ca96jk0llr?svg=true)](https://ci.appveyor.com/project/yegor256/futex)
 [![Gem Version](https://badge.fury.io/rb/futex.svg)](http://badge.fury.io/rb/futex)
 [![Maintainability](https://api.codeclimate.com/v1/badges/5528e182bb5e4a2ecc1f/maintainability)](https://codeclimate.com/github/yegor256/futex/maintainability)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/yegor256/futex/master/frames)
 
 Sometimes you need to synchronize your block of code, but `Mutex` is too coarse-grained,
 because it _always locks_, no matter what objects your code accesses. The
@@ -21,12 +24,23 @@ Then, use it like this:
 ```ruby
 require 'futex'
 Futex.new('/tmp/my-file.txt').open |f|
-  File.write(f, 'Hello, world!')
+  IO.write(f, 'Hello, world!')
 end
 ```
 
 The file `/tmp/my-file.txt.lock` will be created and used as an entrance lock.
-It will be deleted afterwards.
+It <del>will</del> [won't](https://github.com/yegor256/futex/issues/5) be deleted afterwards.
+
+If you are not planning to write to the file, it is recommended to get
+a non-exclusive/shared access to it, by providing `false` to the method
+`open()`:
+
+```ruby
+require 'futex'
+Futex.new('/tmp/my-file.txt').open(false) |f|
+  IO.read(f)
+end
+```
 
 For better traceability you can provide a few arguments to the
 constructor of the `Futex` class, including:

data/Rakefile

@@ -44,6 +44,13 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = false
 end
 
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+end
+
 require 'rubocop/rake_task'
 desc 'Run RuboCop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|

data/appveyor.yml

@@ -0,0 +1,38 @@
+version: '{build}'
+skip_tags: true
+clone_depth: 10
+branches:
+  only:
+    - master
+  except:
+    - gh-pages
+os: Windows Server 2012
+environment:
+  matrix:
+    - ruby_version: "23-x64"
+    - ruby_version: "24-x64"
+    - ruby_version: "25-x64"
+install:
+  - ps: |
+      $Env:PATH = "C:\Ruby${Env:ruby_version}\bin;${Env:PATH}"
+      if ($Env:ruby_version -match "^23" ) {
+        # RubyInstaller; download OpenSSL headers from OpenKnapsack Project
+        $Env:openssl_dir = "C:\Ruby${Env:ruby_version}"
+        appveyor DownloadFile http://dl.bintray.com/oneclick/OpenKnapsack/x64/openssl-1.0.2j-x64-windows.tar.lzma
+        7z e openssl-1.0.2j-x64-windows.tar.lzma
+        7z x -y -oC:\Ruby${Env:ruby_version} openssl-1.0.2j-x64-windows.tar
+      } else {
+        # RubyInstaller2; openssl package seems to be installed already
+        $Env:openssl_dir = "C:\msys64\mingw64"
+      }
+  - bundle config --local path vendor/bundle
+  - bundle config build.openssl --with-openssl-dir=%openssl_dir%
+  - ruby -v
+  - bundle -v
+build_script:
+  - bundle update
+  - bundle install
+test_script:
+  - bundle exec rake --quiet
+cache:
+  - vendor/bundle

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.3.1'
+  s.version = '0.4.0'
   s.license = 'MIT'
   s.summary = 'File-based mutex'
   s.description = 'Ruby Gem for file-based locking'
@@ -42,10 +42,10 @@ Gem::Specification.new do |s|
   s.test_files = s.files.grep(%r{^(test)/})
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md']
-  s.add_development_dependency 'minitest', '~>5'
-  s.add_development_dependency 'rake', '~>12'
-  s.add_development_dependency 'rdoc', '~>4'
-  s.add_development_dependency 'rubocop', '0.58.1'
-  s.add_development_dependency 'rubocop-rspec', '~>1'
-  s.add_development_dependency 'threads', '~>0'
+  s.add_development_dependency 'minitest', '5.11.3'
+  s.add_development_dependency 'rake', '12.3.1'
+  s.add_development_dependency 'rdoc', '4.3.0'
+  s.add_development_dependency 'rubocop', '0.60.0'
+  s.add_development_dependency 'rubocop-rspec', '1.30.1'
+  s.add_development_dependency 'threads', '0.3.0'
 end

data/lib/futex.rb

@@ -25,37 +25,55 @@
 require 'fileutils'
 require 'time'
 
-# Futex.
+# Futex (file mutex) is a fine-grained mutex that uses a file, not an entire
+# thread, like <tt>Mutex</tt> does. Use it like this:
+#
+#  require 'futex'
+#  Futex.new('/tmp/my-file.txt').open |f|
+#    IO.write(f, 'Hello, world!')
+#  end
+#
+# The file <tt>/tmp/my-file.txt.lock<tt> will be created and
+# used as an entrance lock.
+#
+# 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
+# the method <tt>open()</tt>:
+#
+#  require 'futex'
+#  Futex.new('/tmp/my-file.txt').open(false) |f|
+#    IO.read(f)
+#  end
+#
+# For more information read
+# {README}[https://github.com/yegor256/futex/blob/master/README.md] file.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2018 Yegor Bugayenko
 # License:: MIT
 class Futex
+  # Creates a new instance of the class.
   def initialize(path, log: STDOUT, timeout: 16, sleep: 0.005,
     lock: path + '.lock', logging: false)
-    raise "File path can't be nil" if path.nil?
     @path = path
-    raise "Log can't be nil" if log.nil?
     @log = log
-    raise "Logging can't be nil" if logging.nil?
     @logging = logging
-    raise "Timeout can't be nil" if timeout.nil?
-    raise "Timeout must be positive: #{timeout}" unless timeout.positive?
     @timeout = timeout
-    raise "Sleep can't be nil" if sleep.nil?
-    raise "Sleep can't be negative or zero: #{sleep}" unless sleep.positive?
     @sleep = sleep
-    raise "Lock path can't be nil" if lock.nil?
     @lock = lock
   end
 
-  def open
+  # Open the file.
+  def open(exclusive = true)
     FileUtils.mkdir_p(File.dirname(@lock))
     step = (1 / @sleep).to_i
     start = Time.now
     File.open(@lock, File::CREAT | File::RDWR) do |f|
       cycle = 0
       loop do
-        break if f.flock(File::LOCK_EX | File::LOCK_NB)
+        if f.flock((exclusive ? File::LOCK_EX : File::LOCK_SH) | File::LOCK_NB)
+          break
+        end
         sleep(@sleep)
         cycle += 1
         if Time.now - start > @timeout

data/test/test_futex.rb

@@ -25,6 +25,8 @@
 require 'minitest/autorun'
 require 'tmpdir'
 require 'threads'
+require 'digest'
+require 'securerandom'
 require_relative '../lib/futex'
 
 # Futex test.
@@ -59,6 +61,27 @@ class FutexTest < Minitest::Test
     end
   end
 
+  def test_non_exclusive_locking
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'g/e/f/file.txt')
+      Threads.new(20).assert(1000) do |_, r|
+        if (r % 50).zero?
+          Futex.new(path).open do |f|
+            text = SecureRandom.hex(1024)
+            hash = Digest::SHA256.hexdigest(text)
+            IO.write(f, text + ' ' + hash)
+          end
+        end
+        Futex.new(path).open(false) do |f|
+          if File.exist?(f)
+            text, hash = IO.read(f, text).split(' ')
+            assert_equal(hash, Digest::SHA256.hexdigest(text))
+          end
+        end
+      end
+    end
+  end
+
   # This test doesn't work and I can't fix it. If I remove the file
   # afterwards, the flock() logic gets broken. More about it here:
   # https://stackoverflow.com/questions/53011200

metadata

@@ -1,99 +1,99 @@
 --- !ruby/object:Gem::Specification
 name: futex
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Yegor Bugayenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-26 00:00:00.000000000 Z
+date: 2018-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '5'
+        version: 5.11.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '5'
+        version: 5.11.3
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '12'
+        version: 12.3.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '12'
+        version: 12.3.1
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '4'
+        version: 4.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '4'
+        version: 4.3.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.58.1
+        version: 0.60.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.58.1
+        version: 0.60.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '1'
+        version: 1.30.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '1'
+        version: 1.30.1
 - !ruby/object:Gem::Dependency
   name: threads
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
 description: Ruby Gem for file-based locking
 email: yegor256@gmail.com
 executables: []
@@ -110,6 +110,7 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- appveyor.yml
 - futex.gemspec
 - lib/futex.rb
 - test/test_futex.rb