admit_one 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.loadpath
+.project

data/README.md

@@ -0,0 +1,76 @@
+AdmitOne
+========
+
+A Ruby lock file manager that is immune to race conditions.
+
+Usage
+-----
+
+    AdmitOne::LockFile.new(:lock_name) do
+      begin
+        # code that needs to run with confidence
+        # that the same code isn't also running
+        # at the same time in another process
+      rescue AdmitOne::LockFileAlreadyExists
+        # gracefully recover if the lock could not
+        # be established
+      end
+    end
+
+Installation
+------------
+
+    gem install admit_one
+
+Testing
+-------
+
+    rake
+  
+Race Conditions
+---------------
+
+All other Ruby lock file libraries I've examined (I'm sure I've missed some,
+but hey) are susceptible to race conditions, meaning that there's a tiny
+window of opportunity for two separate processes that want the same lock file
+to both *think* that they successfully got the lock, defeating the entire
+purpose of a lock file.
+
+Usually this is caused by one line of code that checks to see if the lock file
+already exists, and if not, a second that creates it. This means two processes
+could each, theoretically, check for the file at the same time, both not find
+one and think it's safe for each of them to create one, and then both do so,
+blissfully ignorant of each other.
+
+Admittedly, this scenario seems highly unlikely, but in some applications
+it could result in a complete disaster in a variety of wonderful flavors,
+and you're not likely to be creating lock files in the first place unless
+it's that very disaster that you absolutely need to prevent.
+
+Solution
+--------
+
+AdmitOne solves this problem by taking advantage of how Ruby opens files in
+append mode. If the file doesn't already exist, it creates it and then opens
+it. Otherwise it just opens it. Then, any writes to the file are appended
+to the end. Two processes can open and write to the file at the same time.
+
+AdmitOne writes the process id to the file, closes the file and then reopens
+it, this time in read mode, to compare it's process id with the one on the
+first line in the file. In the event of a race condition, two process ids
+will be written to the file (remember, append mode), but *only one* can
+possibly be on the first line.
+
+The first process will reopen the lock file in read mode, compare it's process
+id with the one on the first line, see that they match, and only then
+execute your block of code that needed a lock. The second process also opens
+the file, but it will see that the process id on the first line does *not*
+match it's own, and instead of executing the code block, will raise an
+exception for your application to catch and handle gracefully according to
+your preferences (such as trying again later, or triggering a missile launch).   
+
+Contributions
+-------------
+
+If you can see some way to improve upon this gem, feel free to fork, commit
+with tests (if applicable), and then send a pull request. Thank You!

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/admit_one.gemspec

@@ -0,0 +1,18 @@
+require File.expand_path('../lib/admit_one/version',  __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "admit_one"
+  s.version     = AdmitOne::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jonathan S. Garvin"]
+  s.email       = ["jon@5valleys.com"]
+  s.homepage    = "https://github.com/jsgarvin/admit_one"
+  s.summary     = %q{Lock file manager.}
+  s.description = %q{Lock file manager that is immune to race conditions.}
+
+  s.rubyforge_project = "admit_one"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.require_paths = ["lib"]
+end

data/lib/admit_one/lock_file.rb

@@ -0,0 +1,42 @@
+module AdmitOne
+    
+  class LockFile
+    require 'tempfile'
+    
+    attr_accessor :filename
+    
+    def initialize(name,&block)
+      @filename = "#{name}.lock"
+      begin
+        lock!
+        yield
+      ensure
+        unlock!
+      end
+    end
+    
+    def full_path
+      "#{Dir.tmpdir}/#{filename}"
+    end
+    
+    def lock!
+      File.open(full_path, "a") { |file| file.write("#{Process.pid}\n") }
+      raise LockFileAlreadyExists unless lock_file_acquired?
+    end
+    
+    def unlock!
+      begin
+        File.delete(full_path) if lock_file_acquired? 
+      rescue
+        raise LockFileMissing
+      end
+    end
+    
+    def lock_file_acquired?
+      File.open(full_path, "r") { |file| file.gets.to_i == Process.pid }
+    end
+  end
+  
+  class LockFileAlreadyExists < StandardError; end
+  class LockFileMissing < StandardError; end
+end

data/lib/admit_one/version.rb

@@ -0,0 +1,3 @@
+module AdmitOne
+  VERSION = '0.1.0'
+end

data/lib/admit_one.rb

@@ -0,0 +1 @@
+require File.expand_path('../admit_one/lock_file',  __FILE__)

data/test/unit/lock_file_test.rb

@@ -0,0 +1,35 @@
+require File.expand_path('../../../lib/admit_one',  __FILE__)
+require 'test/unit'
+
+class LockFileTest < Test::Unit::TestCase
+  
+  def setup
+    File.delete(lock_file_path) if File.exist?(lock_file_path)
+  end
+  
+  def test_should_create_and_remove_lockfile
+    AdmitOne::LockFile.new(:admit_one_lock_file_unit_test) do
+      assert(File.exist?(lock_file_path))
+    end
+    assert(!File.exist?(lock_file_path))
+  end
+  
+  def test_should_not_clobber_another_lock_file
+    File.open(lock_file_path, "a") { |file| file.write("1\n") }
+    assert_raise(AdmitOne::LockFileAlreadyExists) do
+      AdmitOne::LockFile.new(:admit_one_lock_file_unit_test) do
+        assert false #should never run
+      end
+    end
+    assert(File.exist?(lock_file_path))
+    File.delete(lock_file_path)
+  end
+  
+  #######
+  private
+  #######
+  
+  def lock_file_path
+    "#{Dir.tmpdir}/admit_one_lock_file_unit_test.lock"
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: admit_one
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jonathan S. Garvin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-19 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: Lock file manager that is immune to race conditions.
+email: 
+- jon@5valleys.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- README.md
+- Rakefile
+- admit_one.gemspec
+- lib/admit_one.rb
+- lib/admit_one/lock_file.rb
+- lib/admit_one/version.rb
+- test/unit/lock_file_test.rb
+has_rdoc: true
+homepage: https://github.com/jsgarvin/admit_one
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: admit_one
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Lock file manager.
+test_files: 
+- test/unit/lock_file_test.rb