mega_mutex 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Songkick.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,43 @@
+# mega_mutex
+
+## Why
+
+Sometimes I need to do this:
+
+    unless enough_things?
+      make_more_things
+    end
+    
+Sometimes though, if I'm running lots of processes in parallel, I get a race condition that means two of the processes both think there are not enough things. So we go and make some more, even though we don't need to.
+
+## How
+
+Suppose you have a ThingMaker:
+
+    class ThingMaker
+      include MegaMutex
+      
+      def ensure_just_enough_things  
+        with_cross_process_mutex("ThingMaker Mutex ID") do
+          unless enough_things?
+            make_more_things
+          end
+        end
+      end
+    end
+
+Now, thanks to the magic of MegaMutex, you can be sure that all processes trying to run this code will wait their turn, so each one will have the chance to make exactly the right number of things, without anyone else poking their nose in.
+
+## Configuration
+
+MegaMutex uses [memcache-client](http://seattlerb.rubyforge.org/memcache-client/) to store the mutex, so your infrastructure must be set up to use memcache servers.
+
+By default, MegaMutex will attempt to connect to a memcache on the local machine, but you can configure any number of servers like so:
+
+    MegaMutex.configure do |config|
+      config.memcache_servers = ['mc1', 'mc2']
+    end
+
+## Copyright
+
+Copyright (c) 2009 Songkick.com. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "mega_mutex"
+    gem.summary = %Q{Cross-process mutex using MemCache}
+    gem.description = %Q{Cross-process mutex using MemCache}
+    gem.email = "developers@songkick.com"
+    gem.homepage = "http://github.com/songkick/mega_mutex"
+    gem.authors = ["Matt Johnson", "Matt Wynne"]
+    gem.add_dependency 'memcache-client', '>= 1.7.4'
+    gem.add_dependency 'logging', '>= 1.1.4'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mega_mutex #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/mega_mutex/cross_process_mutex.rb

@@ -0,0 +1,100 @@
+require 'logging'
+require 'memcache'
+
+module MegaMutex
+  class TimeoutError < Exception; end
+
+  class CrossProcessMutex
+
+    class Configuration
+      attr_accessor :memcache_servers
+
+      def initialize
+        @memcache_servers = 'localhost'
+      end
+    end
+
+    class << self
+      def configure
+        yield configuration
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+    end
+    
+    def initialize(key, timeout = nil)
+      @key = key
+      @timeout = timeout
+    end
+
+    def logger
+      Logging::Logger[self]
+    end
+
+    def run(&block)
+      @start_time = Time.now
+      log "Attempting to lock cross-process mutex..."
+      lock!
+      log "Locked. Running critical section..."
+      yield
+      log "Critical section complete. Unlocking..."
+    ensure
+      unlock!
+      log "Unlocking Mutex."
+    end
+    
+  private
+  
+    def timeout?
+      return false unless @timeout
+      Time.now > @start_time + @timeout
+    end
+  
+    def log(message)
+      logger.debug do
+        "(key:#{@key}) (lock_id:#{my_lock_id}) #{message}"
+      end
+    end
+
+    def lock!
+      until timeout?
+        return if attempt_to_lock == my_lock_id
+        sleep 0.1
+      end
+      raise TimeoutError.new("Failed to obtain a lock within #{@timeout} seconds.")
+    end
+    
+    def attempt_to_lock
+      if current_lock.nil?
+        set_current_lock my_lock_id
+      end
+      current_lock
+    end
+    
+    def unlock!
+      cache.delete(@key) if locked_by_me?
+    end
+    
+    def locked_by_me?
+      current_lock == my_lock_id
+    end
+    
+    def current_lock
+      cache.get(@key)
+    end
+    
+    def set_current_lock(new_lock)
+      cache.add(@key, my_lock_id)      
+    end
+    
+    def my_lock_id
+      @my_lock_id ||= "#{Process.pid.to_s}.#{self.object_id.to_s}.#{Time.now.to_i.to_s}"
+    end
+
+    def cache
+      @cache ||= MemCache.new self.class.configuration.memcache_servers, :namespace => 'mega_mutex'
+    end
+  end
+end

data/lib/mega_mutex.rb

@@ -0,0 +1,61 @@
+require 'rubygems'
+$:.push File.expand_path(File.dirname(__FILE__))
+
+require 'mega_mutex/cross_process_mutex'
+
+# == Why
+# 
+# Sometimes I need to do this:
+# 
+#     unless enough_things?
+#       make_more_things
+#     end
+#     
+# Sometimes though, if I'm running lots of processes in parallel, I get a race condition that means two of the processes both think there are not enough things. So we go and make some more, even though we don't need to.
+# 
+# == How
+# 
+# Suppose you have a ThingMaker:
+# 
+#     class ThingMaker
+#       include MegaMutex
+#       
+#       def ensure_just_enough_things  
+#         with_cross_process_mutex("ThingMaker Mutex ID") do
+#           unless enough_things?
+#             make_more_things
+#           end
+#         end
+#       end
+#     end
+# 
+# Now, thanks to the magic of MegaMutex, you can be sure that all processes trying to run this code will wait their turn, so each one will have the chance to make exactly the right number of things, without anyone else poking their nose in.
+# 
+# == Configuration
+# 
+# MegaMutex uses http://seattlerb.rubyforge.org/memcache-client/ to store the mutex, so your infrastructure must be set up to use memcache servers.
+# 
+# By default, MegaMutex will attempt to connect to a memcache on the local machine, but you can configure any number of servers like so:
+# 
+#     MegaMutex.configure do |config|
+#       config.memcache_servers = ['mc1', 'mc2']
+#     end
+module MegaMutex
+
+  ## 
+  # Wraps code that should only be run when the mutex has been obtained.
+  # 
+  # The mutex_id uniquely identifies the section of code being run.
+  #
+  # You can optionally specify a :timeout to control how long to wait for the lock to be released
+  # before raising a MegaMutex::TimeoutError
+  #
+  #   with_cross_process_mutex('my_mutex_id_1234', :timeout => 20) do
+  #     do_something!
+  #   end
+  def with_cross_process_mutex(mutex_id, options = {}, &block)
+    mutex = CrossProcessMutex.new(mutex_id, options[:timeout])
+    mutex.run(&block)
+  end
+
+end

data/mega_mutex.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{mega_mutex}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matt Johnson", "Matt Wynne"]
+  s.date = %q{2009-08-18}
+  s.description = %q{Cross-process mutex using MemCache}
+  s.email = %q{developers@songkick.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "lib/mega_mutex.rb",
+     "lib/mega_mutex/cross_process_mutex.rb",
+     "mega_mutex.gemspec",
+     "spec/lib/mega_mutex_spec.rb"
+  ]
+  s.homepage = %q{http://github.com/songkick/mega_mutex}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Cross-process mutex using MemCache}
+  s.test_files = [
+    "spec/lib/mega_mutex_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<memcache-client>, [">= 1.7.4"])
+      s.add_runtime_dependency(%q<logging>, [">= 1.1.4"])
+    else
+      s.add_dependency(%q<memcache-client>, [">= 1.7.4"])
+      s.add_dependency(%q<logging>, [">= 1.1.4"])
+    end
+  else
+    s.add_dependency(%q<memcache-client>, [">= 1.7.4"])
+    s.add_dependency(%q<logging>, [">= 1.1.4"])
+  end
+end

data/spec/lib/mega_mutex_spec.rb

@@ -0,0 +1,129 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../lib/mega_mutex')
+
+# Logging::Logger[:root].add_appenders(Logging::Appenders.stdout)
+
+module MegaMutex
+  describe MegaMutex do
+    def logger
+      Logging::Logger['Specs']
+    end
+
+    before(:all) do
+      @old_abort_on_exception_value = Thread.abort_on_exception
+      Thread.abort_on_exception = true
+    end
+    after(:all) do
+      Thread.abort_on_exception = @old_abort_on_exception_value
+    end
+
+    describe "two blocks, one fast, one slow" do
+      before(:each) do
+        @errors = []
+        @mutually_exclusive_block = lambda do
+          @errors << "Someone else is running this code!" if @running
+          @running = true
+          sleep 0.5
+          @running = nil
+        end
+      end
+
+      describe "with no lock" do
+        it "trying to run the block twice should raise an error" do
+          threads = []
+          threads << Thread.new(&@mutually_exclusive_block)
+          threads << Thread.new(&@mutually_exclusive_block)
+          threads.each{ |t| t.join }
+          @errors.should_not be_empty
+        end
+      end
+
+      describe "with the same lock key" do
+        before(:each) do
+          MemCache.new('localhost').delete(mutex_id)
+        end
+
+        def mutex_id
+          'tests-mutex-key'
+        end
+
+        include MegaMutex
+
+        [2, 20].each do |n|
+          describe "when #{n} blocks try to run at the same instant in the same process" do
+            it "should run each in turn" do
+              threads = []
+              n.times do
+                threads << Thread.new{ with_cross_process_mutex(mutex_id, &@mutually_exclusive_block) }
+              end
+              threads.each{ |t| t.join }
+              @errors.should be_empty
+            end
+          end
+        end
+
+        describe "when the first block raises an exception" do
+          before(:each) do
+            with_cross_process_mutex(mutex_id) do
+              raise "Something went wrong in my code"
+            end rescue nil
+          end
+
+          it "the second block should find that the lock is clear and it can run" do
+            @success = nil
+            with_cross_process_mutex(mutex_id) do
+              @success = true
+            end
+            @success.should be_true
+          end
+        end
+
+        describe "when two blocks try to run at the same instant in different processes" do
+          before(:each) do
+            @lock_file   = File.expand_path(File.dirname(__FILE__) + '/tmp_lock')
+            @errors_file = File.expand_path(File.dirname(__FILE__) + '/tmp_errors')
+            @mutually_exclusive_block = lambda {
+              File.open(@errors_file, 'w').puts "Someone else is running this code!" if File.exists?(@lock_file)
+              FileUtils.touch @lock_file
+              sleep 1
+              File.delete @lock_file
+            }
+          end
+
+          after(:each) do
+            File.delete @lock_file   if File.exists?(@lock_file)
+            File.delete @errors_file if File.exists?(@errors_file)
+          end
+
+          it "should run each in turn" do
+            pids = []
+            pids << fork { with_cross_process_mutex(mutex_id, &@mutually_exclusive_block); Kernel.exit! }
+            pids << fork { with_cross_process_mutex(mutex_id, &@mutually_exclusive_block); Kernel.exit! }
+            pids.each{ |p| Process.wait(p) }
+            if File.exists?(@errors_file)
+              raise "Expected no errors but found #{File.read(@errors_file)}"
+            end
+          end
+        end
+
+      end
+    end
+  
+    describe "with a timeout" do
+      include MegaMutex
+      it "should raise an error if the code blocks for longer than the timeout" do
+        @success = false
+        threads = []
+        threads << Thread.new{ with_cross_process_mutex('foo'){ sleep 2 } }
+        threads << Thread.new do
+          begin
+            with_cross_process_mutex('foo', :timeout => 1 ){ puts 'nobody will ever hear me scream' } 
+          rescue MegaMutex::TimeoutError
+            @success = true
+          end
+        end
+        threads.each{ |t| t.join }
+        @success.should be_true
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: mega_mutex
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matt Johnson
+- Matt Wynne
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-18 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: memcache-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: logging
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.4
+    version: 
+description: Cross-process mutex using MemCache
+email: developers@songkick.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/mega_mutex.rb
+- lib/mega_mutex/cross_process_mutex.rb
+- mega_mutex.gemspec
+- spec/lib/mega_mutex_spec.rb
+has_rdoc: true
+homepage: http://github.com/songkick/mega_mutex
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Cross-process mutex using MemCache
+test_files: 
+- spec/lib/mega_mutex_spec.rb