cromwell 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+tmp
+scratch_directory

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Przemyslaw Kowalczyk
+
+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.rdoc

@@ -0,0 +1,139 @@
+= Cromwell
+
+Lord Protector of your scripts.
+
+== Description
+
+This is a very simple wrapper over <code>Signal#trap</code> method that allows you to easily protect your scripts from being killed while they are doing something that should not be interrupted (e.g. interacting with some non-transactional service) or is too costly to restart (e.g. long computations).
+
+While inside the protected block, your script will ignore certain signals and continue its work, but if a signal was caught, it will terminate once the protected block is over. By default, only following signals are ignored: <code>INT</code> (keyboard interrupt <code>^C</code>), <code>TERM</code> (sent by <code>kill</code> by defautl), <code>HUP</code> (sent when shell terminates), and <code>QUIT</code> (a "dump core" signal, sent with <code>^\\</code>), but you can specify any list of them (except for <code>KILL</code> and <code>STOP</code>, of course).
+
+For a full signal list supported on your operating system, run <code>Signal.list</code> in your <code>irb</code>. For more info on signals and their meaning, check your local <code>man signal</code>.
+
+This gem is based on real-life production code. It is especially useful for protecting various daemon-like scripts in Rails application that are (might be) restarted with every deploy.
+
+== Usage examples
+
+The most important in Cromwell API is the <code>protect</code> method. It can be called in two ways: with a block and without a block.
+
+=== Block form
+
+When used with a block, Cromwell executes the code inside the block protecting it from being interrupted with a signal:
+
+  puts 'See you in a while...'
+  Cromwell.protect {
+    sleep 10
+  }
+  puts "You're still here?"
+
+When you run this script (which lives in <code>examples/example1.rb</code>), you won't be able to interrupt it with <code>^C</code> or simple <code>kill</code> while it's sleeping for ten seconds:
+
+  $ ruby examples/example1.rb
+  See you in a while...
+  ^C^C^C^C
+  [ ten seconds pass... ]
+  $
+
+Because I tried to interrupt the script, it was terminated once the protected block was over. Had I not pressed <code>^C</code>, the last line would be executed:
+
+  $ ruby examples/example1.rb
+  See you in a while...
+  [ ten seconds pass... ]
+  You're still here?
+  $
+
+The script cannot be killed, too (I run it in background to be able to run other commands in the same shell):
+
+  $ ruby examples/example1.rb &
+  [1] 70300
+  See you in a while...
+  $ kill 70300
+  [ ten seconds pass... ]
+  $
+  [1]+  Done                    ruby examples/example1.rb
+
+If you really want to kill it, use <code>kill -9</code>:
+
+  $ ruby examples/example1.rb &
+  [1] 70328
+  See you in a while...
+  $ kill -9 70328
+  $
+  [1]+  Killed                  ruby examples/example1.rb
+
+=== Non-block form
+
+If you want to have more control over what's protected in your script, you can use <code>protect</code> without the block. In that case your code will be protected until you call <code>unprotect</code> method:
+
+  puts 'See you in a while...'
+  Cromwell.protect
+  sleep 10
+  Cromwell.unprotect
+  puts "You're still here?"
+
+The above code lives in <code>examples/example2.rb</code> and behaves in the same way as previous example.
+
+In general it might be good idea to place the call to <code>unprotect</code> in an <code>ensure</code> block. Or, if you want your script to just run until it finishes on its own, don't call <code>unprotect</code> at all.
+
+=== Specifying other signals
+
+If you want to protect from other signals than the default list, specify them as parameters to <code>protect</code> method:
+
+  puts "You can't stop me with ^C but you can kill me. My pid is #{$$}."
+  Cromwell.protect("INT") {
+    sleep 10
+  }
+  puts "You're still here?"
+
+This script is still immune to <code>^C</code>:
+
+  $ ruby examples/example3.rb
+  You can't stop me with ^C but you can kill me. My pid is 70243.
+  ^C^C^C^C
+  [ ten seconds pass... ]
+  $
+
+But can be killed:
+
+  $ ruby examples/example3.rb &
+  [1] 70245
+  You can't stop me with ^C but you can kill me. My pid is 70245.
+  $ kill 70245
+  [1]+  Terminated              ruby examples/example3.rb
+  $
+
+=== Inspecting state
+
+You can inspect Cromwell's state with two methods:
+
+* <code>Cromwell.protected?</code> returns <code>true</code> when your code is protected, <code>false</code> otherwise.
+* <code>Cromwell.should_exit?</code> returns <code>true</code> when a signal was caught and termination will ocur after the protected code is over.
+
+== Compatibility
+
+Works for me. Tested on Mac OS X 10.4--10.6 and a little bit on Debian Linux. If it works for you too, I'd be glad to know. Cromwell's reliability depends heavily on your operating system's signals implementation reliability (which may not be very stable on some systems).
+
+== To Do list
+
+* Remove traps when they are not needed anymore. Currently they remain in place and when you call protect again (even with different signals list), the old ones are still effective.
+* Allow to customize behavior after catching a signal. Right now, the script is terminated after the protected block is done (even if the signal would not normally cause script termination).
+* Play well with other trap handlers that might be installed.
+* Add logger support.
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Note on terminology
+
+The protection from signals provided by Cromwell and the method names <code>protect</code>, <code>unprotect</code>, and <code>protected?</code> have <b>nothing</b> to do with Ruby's <code>protected</code> keyword and the general concept of a <i>protected</i> method in Ruby and other object-oriented languages.
+
+== Copyright
+
+Copyright (c) 2009 Przemyslaw Kowalczyk. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,94 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "cromwell"
+    gem.summary = %Q{Lord Protector of your scripts}
+    gem.description = %Q{A very simple wrapper over Signal#trap method that allows you to easily protect your scripts from being killed while they are doing something that should not be interrupted (e.g. interacting with some non-transactional service) or is too costly to restart (e.g. long computations). }
+    gem.email = "szeryf@negativeiq.pl"
+    gem.homepage = "http://github.com/szeryf/cromwell"
+    gem.authors = ["Przemyslaw Kowalczyk"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 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: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.rcov_opts << "-x /gems/"
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "cromwell #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'metric_fu'
+rescue LoadError
+  puts "metric_fu (or a dependency) not available. If you want to run metrics, install it with: gem install metric_fu"
+end
+
+MetricFu::Configuration.run do |config|
+  #define which metrics you want to use
+  config.metrics  = [:churn, :saikuro, :flog, :flay, :reek, :roodi, :rcov]
+  config.graphs   = []
+  config.flay     = { :dirs_to_flay  => ['lib']  }
+  config.flog     = { :dirs_to_flog  => ['lib']  }
+  config.reek     = { :dirs_to_reek  => ['lib']  }
+  config.roodi    = { :dirs_to_roodi => ['lib'] }
+  config.saikuro  = { :output_directory => 'scratch_directory/saikuro',
+                      :input_directory => ['lib'],
+                      :cyclo => "",
+                      :filter_cyclo => "0",
+                      :warn_cyclo => "5",
+                      :error_cyclo => "7",
+                      :formater => "text"} #this needs to be set to "text"
+  config.churn    = { :start_date => "1 year ago", :minimum_churn_count => 10}
+  config.rcov     = { :test_files => ['test/**/test_*.rb'],
+                      :rcov_opts => ["--sort coverage",
+                                     "--no-html",
+                                     "--text-coverage",
+                                     "--no-color",
+                                     "--exclude /gems/,/Library/,spec"]}
+end
+
+# fix for failing on NaN
+module MetricFu
+  class Generator
+    def round_to_tenths(decimal)
+      decimal=0.0 if decimal.to_s.eql?('NaN')
+      (decimal.to_i * 10).round / 10.0
+    end
+  end
+end

data/VERSION

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

data/cromwell.gemspec

@@ -0,0 +1,60 @@
+# 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{cromwell}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Przemyslaw Kowalczyk"]
+  s.date = %q{2010-01-03}
+  s.description = %q{A very simple wrapper over Signal#trap method that allows you to easily protect your scripts from being killed while they are doing something that should not be interrupted (e.g. interacting with some non-transactional service) or is too costly to restart (e.g. long computations). }
+  s.email = %q{szeryf@negativeiq.pl}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "cromwell.gemspec",
+     "examples/example1.rb",
+     "examples/example2.rb",
+     "examples/example3.rb",
+     "lib/cromwell.rb",
+     "test/helper.rb",
+     "test/test_cromwell.rb"
+  ]
+  s.homepage = %q{http://github.com/szeryf/cromwell}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Lord Protector of your scripts}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_cromwell.rb",
+     "examples/example1.rb",
+     "examples/example2.rb",
+     "examples/example3.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_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+  end
+end
+

data/examples/example1.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'cromwell'
+
+puts 'See you in a while...'
+Cromwell.protect {
+  sleep 10
+}
+puts "You're still here?"

data/examples/example2.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'cromwell'
+
+puts 'See you in a while...'
+Cromwell.protect
+sleep 10
+Cromwell.unprotect
+puts "You're still here?"

data/examples/example3.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'cromwell'
+
+puts "You can't stop me with ^C but you can kill me. My pid is #{$$}."
+Cromwell.protect("INT") {
+  sleep 10
+}
+puts "You're still here?"

data/lib/cromwell.rb

@@ -0,0 +1,74 @@
+class Cromwell
+  DEFAULT_SIGNAL_LIST = %w[INT TERM HUP QUIT].freeze
+
+  class << self
+    # call-seq:
+    #   Cromwell.protect(*signals) { ... some code ... }
+    #   Cromwell.protect(*signals)
+    #   Cromwell.protect { ... some code ... }
+    #   Cromwell.protect
+    #
+    # Starts protecting your code. If called with a block, only the code within a block is
+    # executed with signal protection. Without a block, script is protected until unprotect
+    # is called. Signals can be given in all the forms that <code>Signal#trap</code> recognizes.
+    # Without parameters, the code is protected from the signals in DEFAULT_SIGNAL_LIST.
+    # More info and examples in README.rdoc.
+    def protect *signals
+      set_up_traps(signals.empty? ? DEFAULT_SIGNAL_LIST : signals.flatten)
+      @@should_exit = false
+      @@protected   = true
+      if block_given?
+        begin
+          yield
+        ensure
+          unprotect
+        end
+      end
+    end
+
+    # call-seq:
+    #   Cromwell.unprotect
+    #
+    # Turns off protection from signals. Will terminate the script with <code>Kernel#exit</code>
+    # if signal was caught earlier (so any <code>at_exit</code> code will be executed).
+    # The protect method calls this automatically when executed with a block.
+    def unprotect
+      @@protected = false
+      exit if @@should_exit
+    end
+
+    # call-seq:
+    #   Cromwell.should_exit?
+    #
+    # True when the script will be terminated after protected block, i.e. when a signal
+    # was caught that was protected from.
+    def should_exit?
+      @@should_exit
+    end
+
+    # call-seq:
+    #   Cromwell.protected?
+    #
+    # True if the protection is currently active.
+    def protected?
+      @@protected
+    end
+
+  private
+    def set_up_traps signals
+      signals.each { |signal| set_up_trap signal }
+    end
+
+    def set_up_trap signal
+      trap signal do
+        if @@protected
+          #puts "Just a minute now."
+          @@should_exit = true
+          "IGNORE"
+        else
+          exit
+        end
+      end
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'cromwell'
+
+class Test::Unit::TestCase
+  def assert_slept_at_least seconds, message
+    Process.waitpid @pid
+    end_time = Time.now
+    assert end_time - @start_time >= seconds, message
+  end
+
+  def assert_killed_before seconds, message
+    Process.waitpid @pid
+    end_time = Time.now
+    assert end_time - @start_time < seconds, message
+  end
+
+  def do_fork &block
+    @pid = fork(&block)
+  end
+
+  def start
+    @start_time = Time.now
+    sleep 1 # so the forked process gets to execute protected block
+  end
+end

data/test/test_cromwell.rb

@@ -0,0 +1,141 @@
+require 'helper'
+
+class TestCromwell < Test::Unit::TestCase
+
+  # The tests below are hackish and slow, because I had to use sleep to find out whether
+  # forked process was killed or not. If you know a better (and portable!) way to do it,
+  # please let me know.
+  #
+  # On my OS X 10.5:
+  # - Process.kill always returns 1
+  # - Process.waitpid(@pid) always returns @pid
+  # - Process.waitpid(@pid, Process::WNOHANG) always returns nil
+  # so these methods cannot be used to determine if the forked process is still alive :(
+
+  PROCS = {
+    "block form" => proc {
+      Cromwell.protect("HUP") { sleep 3 }
+    },
+    "non block form" => proc {
+      Cromwell.protect "HUP"
+      sleep 3
+      Cromwell.unprotect
+    },
+  }
+
+  PROCS.each do |name, code|
+    context "general functionality of #{name}" do
+      setup do
+        do_fork &code
+        start
+      end
+
+      should "protect from given signal" do
+        Process.kill("HUP", @pid)
+        assert_slept_at_least 3, "child should not be killed before 3 seconds"
+      end
+
+      should "not protect from other signals" do
+        Process.kill("TERM", @pid)
+        assert_killed_before 3, "child should be killed before 3 seconds"
+      end
+    end
+  end
+
+  context "general functionality" do
+    PROCS2 = {
+      "block form" => proc {
+        Cromwell.protect { sleep 3 }
+      },
+      "non block form" => proc {
+        Cromwell.protect
+        sleep 3
+        Cromwell.unprotect
+      },
+    }
+
+    PROCS2.each do |name, code|
+      context name do
+        should "protect from default signals" do
+          do_fork &code
+          start
+
+          Cromwell::DEFAULT_SIGNAL_LIST.each do |signal|
+            Process.kill(signal, @pid)
+          end
+          assert_slept_at_least 3, "child should not be killed before 3 seconds"
+        end
+
+        should "exit right after protected block" do
+          do_fork {
+            code.call
+            sleep 10
+          }
+          start
+
+          Process.kill("HUP", @pid)
+          assert_killed_before  4, "child should be killed after 3 seconds"
+        end
+      end
+    end
+  end # general functionality
+
+  context "method protect" do
+    should "set up trap with given signals" do
+      Cromwell.expects(:set_up_traps).with(["HUP", "TERM"])
+      Cromwell.protect "HUP", "TERM"
+    end
+
+    should "set up trap with default signals" do
+      Cromwell.expects(:set_up_traps).with(Cromwell::DEFAULT_SIGNAL_LIST)
+      Cromwell.protect
+    end
+
+    should "assign false to should_exit" do
+      Cromwell.protect
+      assert !Cromwell.should_exit?
+    end
+
+    should "assign true to protected" do
+      Cromwell.protect
+      assert Cromwell.protected?
+    end
+
+  end # method protect
+
+  context "method protect with block" do
+    should "yield to block" do
+      im_in_ur_blok_touchin_ur_vars = false
+      Cromwell.protect {
+        im_in_ur_blok_touchin_ur_vars = true
+      }
+      assert im_in_ur_blok_touchin_ur_vars
+    end
+
+    should "call unprotect after block is finished" do
+      Cromwell.protect { i = 1 }
+      assert !Cromwell.protected?
+    end
+
+    should "assign true to protected inside block" do
+      Cromwell.protect {
+        assert Cromwell.protected?
+      }
+    end
+  end # method protect with block
+
+  context "method unprotect" do
+    should "assign false to protected" do
+      Cromwell.protect
+      Cromwell.unprotect
+      assert !Cromwell.protected?
+    end
+
+    should "terminate if should_exit is true" do
+      Cromwell.send(:class_variable_set, "@@should_exit", true)
+      Cromwell.expects(:exit)
+      Cromwell.unprotect
+    end
+  end # method unprotect
+
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: cromwell
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Przemyslaw Kowalczyk
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-03 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: "A very simple wrapper over Signal#trap method that allows you to easily protect your scripts from being killed while they are doing something that should not be interrupted (e.g. interacting with some non-transactional service) or is too costly to restart (e.g. long computations). "
+email: szeryf@negativeiq.pl
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- cromwell.gemspec
+- examples/example1.rb
+- examples/example2.rb
+- examples/example3.rb
+- lib/cromwell.rb
+- test/helper.rb
+- test/test_cromwell.rb
+has_rdoc: true
+homepage: http://github.com/szeryf/cromwell
+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.5
+signing_key: 
+specification_version: 3
+summary: Lord Protector of your scripts
+test_files: 
+- test/helper.rb
+- test/test_cromwell.rb
+- examples/example1.rb
+- examples/example2.rb
+- examples/example3.rb