mega_mutex-dalli 0.3.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/History.txt

@@ -0,0 +1,4 @@
+== 0.3.0
+
+Bugfixes:
+  * #with_distributed_mutex was not returning the result of the block

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,54 @@
+# mega_mutex
+
+A distributed mutex for Ruby.
+
+## Why
+
+Sometimes I need to do this:
+
+    unless enough_things?
+      make_more_things
+    end
+    
+If I'm running several processes in parallel, I can 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_distributed_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.
+
+## Install
+
+    sudo gem install mega_mutex
+
+
+## Configure
+
+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
+
+## Help
+
+MegaMutex was built by the [Songkick.com](http://www.songkick.com) development team. Come chat to us on [#songkick](irc://chat.freenode.net/#songkick) on freenode.net.
+
+## Copyright
+
+Copyright (c) 2009 Songkick.com. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "mega_mutex-dalli"
+    gem.summary = %Q{Distributed mutex for Ruby using the Dalli memcached client}
+    gem.description = %Q{Distributed mutex for Ruby using Dalli memcached client}
+    gem.email = "developers@songkick.com"
+    gem.homepage = "http://github.com/msaffitz/mega_mutex-dalli"
+    gem.authors = ["Matt Johnson", "Matt Wynne", "Michael Saffitz"]
+    gem.add_dependency 'dalli', '>= 1.0.0'
+    gem.add_dependency 'logging', '>= 1.1.4'
+    gem.add_dependency 'retryable', ">= 0.1.0"
+    # 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
+
+namespace :github do
+  task :push do
+    remotes = `git remote`.split("\n")
+    unless remotes.include?('github')
+      sh('git remote add github git@github.com:msaffitz/mega_mutex-dalli.git')
+    end
+    sh('git push github master')
+  end
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => [:spec, 'github:push', 'gemcutter:release']
+
+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-dalli #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/mega_mutex.rb

@@ -0,0 +1,106 @@
+require 'rubygems'
+$:.push File.expand_path(File.dirname(__FILE__)) unless $:.include?(File.expand_path(File.dirname(__FILE__)))
+require 'mega_mutex/distributed_mutex'
+
+# == Why
+# 
+# Sometimes I need to do this:
+# 
+#     unless enough_things?
+#       make_more_things
+#     end
+#     
+# If I'm running several processes in parallel, I can 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 https://github.com/mperham/dalli to store the mutex, so your infrastructure must be set up to use memcache servers.
+# 
+# By default, MegaMutex will attempt to connect to either ENV['MEMCACHE_SERVERS'] or localhost, but you can configure any number of servers like so:
+# 
+#     MegaMutex.configure do |config|
+#       config.memcache_servers = ['mc1', 'mc2']
+#     end
+module MegaMutex
+  
+  def self.get_current_lock(mutex_id)
+    DistributedMutex.new(mutex_id).current_lock
+  end
+
+  ## 
+  # 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_distributed_mutex('my_mutex_id_1234', :timeout => 20) do
+  #     do_something!
+  #   end
+  def with_distributed_mutex(mutex_id, options = {}, &block)
+    mutex = DistributedMutex.new(mutex_id, options[:timeout])
+    begin
+      mutex.run(&block)
+    rescue Object => e
+      mega_mutex_insert_into_backtrace(
+        e, 
+        /mega_mutex\.rb.*with_(distributed|cross_process)_mutex/, 
+        "MegaMutex lock #{mutex_id}"
+      )
+      raise e
+    end
+  end
+  alias :with_cross_process_mutex :with_distributed_mutex
+
+  # inserts a line into a backtrace at the correct location
+  def mega_mutex_insert_into_backtrace(exception, re, newline)
+    loc = nil
+    exception.backtrace.each_with_index do |line, index|
+      if line =~ re
+        loc = index
+        break
+      end
+    end
+    if loc
+      exception.backtrace.insert(loc, newline)
+    end
+  end
+  
+  class Configuration
+    attr_accessor :memcache_servers, :namespace
+
+    def initialize
+      @namespace = 'mega_mutex'
+    end
+  end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end
+

data/lib/mega_mutex/distributed_mutex.rb

@@ -0,0 +1,94 @@
+require 'logging'
+require 'dalli'
+require 'retryable'
+
+module MegaMutex
+  class TimeoutError < Exception; end
+
+  class DistributedMutex
+
+    class << self
+      def cache
+        @cache ||= Dalli::Client.new MegaMutex.configuration.memcache_servers, :namespace => MegaMutex.configuration.namespace
+      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 mutex..."
+      lock!
+      log "Locked. Running critical section..."
+      result = yield
+      log "Critical section complete. Unlocking..."
+      result
+    ensure
+      unlock!
+      log "Unlocking Mutex."
+    end
+    
+    def current_lock
+      cache.get(@key)
+    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?
+        retryable(:tries => 5, :sleep => 30, :on => Dalli::NetworkError) do
+          return if attempt_to_lock == my_lock_id
+          sleep 0.1
+        end
+      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!
+      retryable(:tries => 5, :sleep => 30, :on => Dalli::NetworkError) do
+        cache.delete(@key) if locked_by_me?
+      end
+    end
+    
+    def locked_by_me?
+      current_lock == my_lock_id
+    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
+      self.class.cache
+    end
+  end
+end

data/mega_mutex-dalli.gemspec

@@ -0,0 +1,62 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{mega_mutex-dalli}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matt Johnson", "Matt Wynne", "Michael Saffitz"]
+  s.date = %q{2011-01-24}
+  s.description = %q{Distributed mutex for Ruby using Dalli memcached client}
+  s.email = %q{developers@songkick.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "lib/mega_mutex.rb",
+     "lib/mega_mutex/distributed_mutex.rb",
+     "mega_mutex-dalli.gemspec",
+     "spec/lib/mega_mutex_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/msaffitz/mega_mutex-dalli}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Distributed mutex for Ruby using the Dalli memcached client}
+  s.test_files = [
+    "spec/lib/mega_mutex_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<dalli>, [">= 1.0.0"])
+      s.add_runtime_dependency(%q<logging>, [">= 1.1.4"])
+      s.add_runtime_dependency(%q<retryable>, [">= 0.1.0"])
+    else
+      s.add_dependency(%q<dalli>, [">= 1.0.0"])
+      s.add_dependency(%q<logging>, [">= 1.1.4"])
+      s.add_dependency(%q<retryable>, [">= 0.1.0"])
+    end
+  else
+    s.add_dependency(%q<dalli>, [">= 1.0.0"])
+    s.add_dependency(%q<logging>, [">= 1.1.4"])
+    s.add_dependency(%q<retryable>, [">= 0.1.0"])
+  end
+end
+

data/spec/lib/mega_mutex_spec.rb

@@ -0,0 +1,133 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+module MegaMutex
+  describe MegaMutex do
+    include MegaMutex
+
+    def logger
+      Logging::Logger['Specs']
+    end
+    
+    abort_on_thread_exceptions
+
+    describe "#with_distributed_mutex" do
+      it "returns the value returned by the block" do
+        result = with_distributed_mutex("mutex-key") { 12345 }
+        result.should == 12345
+      end
+    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 << Thread.new(&@mutually_exclusive_block)
+          threads << Thread.new(&@mutually_exclusive_block)
+          wait_for_threads_to_finish
+          @errors.should_not be_empty
+        end
+      end
+
+      describe "with the same lock key" do
+        before(:each) do
+          Dalli::Client.new('localhost').delete(mutex_id)
+        end
+
+        def mutex_id
+          'tests-mutex-key'
+        end
+
+        [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
+              n.times do
+                threads << Thread.new{ with_distributed_mutex(mutex_id, &@mutually_exclusive_block) }
+              end
+              wait_for_threads_to_finish
+              @errors.should be_empty
+            end
+          end
+        end
+
+        describe "when the first block raises an exception" do
+          before(:each) do
+            with_distributed_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_distributed_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_distributed_mutex(mutex_id, &@mutually_exclusive_block); Kernel.exit! }
+            pids << fork { with_distributed_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
+
+      it "should raise an error if the code blocks for longer than the timeout" do
+        @exception = nil
+        @first_thread_has_started = false
+        threads << Thread.new do
+          with_distributed_mutex('foo') do
+            @first_thread_has_started = true
+            sleep 0.2
+          end
+        end
+        threads << Thread.new do
+          sleep 0.1 until @first_thread_has_started
+          begin
+            with_distributed_mutex('foo', :timeout => 0.1 ) do
+              raise 'this code should never run'
+            end
+          rescue Exception => @exception
+          end
+        end
+        wait_for_threads_to_finish
+        assert @exception.is_a?(MegaMutex::TimeoutError), "Expected TimeoutError to be raised, but wasn't"
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,32 @@
+require File.expand_path(File.dirname(__FILE__) + '/../lib/mega_mutex')
+require 'test/unit/assertions'
+
+# Logging::Logger[:root].add_appenders(Logging::Appenders.stdout)
+
+module ThreadHelper
+  def abort_on_thread_exceptions
+    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
+  end
+end
+
+module ThreadExampleHelper
+  def threads
+    @threads ||= []
+  end
+  
+  def wait_for_threads_to_finish
+    threads.each{ |t| t.join }
+  end
+end
+
+Spec::Runner.configure do |config|
+  config.extend ThreadHelper
+  config.include ThreadExampleHelper
+  config.include Test::Unit::Assertions
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: mega_mutex-dalli
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Matt Johnson
+- Matt Wynne
+- Michael Saffitz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-24 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: dalli
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: logging
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 1
+        - 4
+        version: 1.1.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: retryable
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
+  type: :runtime
+  version_requirements: *id003
+description: Distributed mutex for Ruby using Dalli memcached client
+email: developers@songkick.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- History.txt
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/mega_mutex.rb
+- lib/mega_mutex/distributed_mutex.rb
+- mega_mutex-dalli.gemspec
+- spec/lib/mega_mutex_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/msaffitz/mega_mutex-dalli
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Distributed mutex for Ruby using the Dalli memcached client
+test_files: 
+- spec/lib/mega_mutex_spec.rb
+- spec/spec_helper.rb