cromwell 0.3.0 → 0.4.0

data/README.rdoc

@@ -6,9 +6,9 @@ Lord Protector of your scripts.
 
 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).
+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: +INT+ (keyboard interrupt <code>^C</code>), +TERM+ (sent by +kill+ by defautl), +HUP+ (sent when shell terminates), and +QUIT+ (a "dump core" signal, sent with <code>^\\</code>), but you can specify any list of them (except for +KILL+ and +STOP+, 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>.
+For a full signal list supported on your operating system, run <code>Signal.list</code> in your +irb+. 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.
 
@@ -24,7 +24,7 @@ If you plan on changing anything, you should run tests and tests require two add
 
 == 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.
+The most important in Cromwell API is the +protect+ method. It can be called in two ways: with a block and without a block.
 
 === Block form
 
@@ -36,7 +36,7 @@ When used with a block, Cromwell executes the code inside the block protecting i
   }
   puts "You're still here?"
 
-When you run this script (which lives in {examples/example1.rb}[http://github.com/szeryf/cromwell/blob/master/examples/example1.rb]), you won't be able to interrupt it with <code>^C</code> or simple <code>kill</code> while it's sleeping for ten seconds:
+When you run this script (which lives in {examples/example1.rb}[http://github.com/szeryf/cromwell/blob/master/examples/example1.rb]), you won't be able to interrupt it with <code>^C</code> or simple +kill+ while it's sleeping for ten seconds:
 
   $ ruby examples/example1.rb
   See you in a while...
@@ -73,7 +73,7 @@ If you really want to kill it, use <code>kill -9</code>:
 
 === 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:
+If you want to have more control over what's protected in your script, you can use +protect+ without the block. In that case your code will be protected until you call +unprotect+ method:
 
   puts 'See you in a while...'
   Cromwell.protect
@@ -83,11 +83,11 @@ If you want to have more control over what's protected in your script, you can u
 
 The above code lives in {examples/example2.rb}[http://github.com/szeryf/cromwell/blob/master/examples/example2.rb] 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.
+In general it might be good idea to place the call to +unprotect+ in an +ensure+ block. Or, if you want your script to just run until it finishes on its own, don't call +unprotect+ 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:
+If you want to protect from other signals than the default list, specify them as parameters to +protect+ method:
 
   puts "You can't stop me with ^C but you can kill me. My pid is #{$$}."
   Cromwell.protect("INT") {
@@ -116,8 +116,8 @@ But can be killed:
 
 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.
+* <code>Cromwell.protected?</code> returns +true+ when your code is protected, +false+ otherwise.
+* <code>Cromwell.should_exit?</code> returns +true+ when a signal was caught and termination will ocur after the protected code is over.
 
 === Preventing termination
 
@@ -195,7 +195,7 @@ Here's an example of logger usage:
   }
   puts "You're still here?"
 
-When run, this script will log messages on <code>STDOUT</code>:
+When run, this script will log messages on +STDOUT+:
 
   $ ruby examples/example6.rb
   See you in a while...
@@ -206,16 +206,64 @@ When run, this script will log messages on <code>STDOUT</code>:
   I, [2010-01-14T11:59:37.872514 #19011]  INFO -- : Exiting because should_exit is true
   $
 
+=== Custom traps
+
+Starting with version 0.4, you can provide your own trap to handle signal. Possible uses of this feature that I can imagine:
+
+* ask user for password so only admin can kill the script,
+* setup some counter and exit the script after 3 signals,
+* handle some signals differently.
+
+In the following example ({examples/example7.rb}[http://github.com/szeryf/cromwell/blob/master/examples/example7.rb]), +SIGINT+ is ignored completely, while +SIGQUIT+ is handled normally (exit after protected block), but with a message:
+
+  Cromwell.custom_traps["INT"] = proc {
+    puts "Trying your ^C skills, are you?"
+  }
+
+  Cromwell.custom_traps["QUIT"] = proc {
+    puts "We'll be leaving soon!"
+    Cromwell.should_exit = true
+  }
+
+  puts 'See you in a while...'
+  Cromwell.protect {
+    sleep 10
+  }
+  puts "You're still here?"
+
+Let's see it in action:
+
+  $ ruby examples/example7.rb
+  See you in a while...
+  ^CTrying your ^C skills, are you?
+  [ ten seconds pass... ]
+  You're still here?
+  $
+
+The last message printed means that the script was not terminated after protected block because the signal trap did not set +should_exit+ to +true+. And now, let's try sending +SIGQUIT+:
+
+  $ ruby examples/example7.rb
+  See you in a while...
+  ^\We'll be leaving soon!
+  [ ten seconds pass... ]
+  $
+
+This time the script didn't get to execute the last +puts+ statement.
+
 == 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
 
-* 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).
+* Empty for now... If you miss some feature, let me know.
 
 == Changelog
 
+=== 0.4
+
+* Added custom traps.
+
 === 0.3
 
 * Added logger support.
@@ -241,7 +289,7 @@ Works for me. Tested on Mac OS X 10.4--10.6 and a little bit on Debian Linux. If
 
 == 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.
+The protection from signals provided by Cromwell and the method names +protect+, +unprotect+, and <code>protected?</code> have <b>nothing</b> to do with Ruby's +protected+ keyword and the general concept of a <i>protected</i> method in Ruby and other object-oriented languages.
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/cromwell.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cromwell}
-  s.version = "0.3.0"
+  s.version = "0.4.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-14}
+  s.date = %q{2010-01-31}
   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 = [
@@ -30,6 +30,7 @@ Gem::Specification.new do |s|
      "examples/example4.rb",
      "examples/example5.rb",
      "examples/example6.rb",
+     "examples/example7.rb",
      "lib/cromwell.rb",
      "test/helper.rb",
      "test/test_cromwell.rb"
@@ -47,7 +48,8 @@ Gem::Specification.new do |s|
      "examples/example3.rb",
      "examples/example4.rb",
      "examples/example5.rb",
-     "examples/example6.rb"
+     "examples/example6.rb",
+     "examples/example7.rb"
   ]
 
   if s.respond_to? :specification_version then

data/examples/example7.rb

@@ -0,0 +1,19 @@
+# ensure that we use ../lib/cromwell.rb, not the installed gem
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'cromwell'
+
+Cromwell.custom_traps["INT"] = proc {
+  puts "Trying your ^C skills, are you?"
+}
+
+Cromwell.custom_traps["QUIT"] = proc {
+  puts "We'll be leaving soon!"
+  Cromwell.should_exit = true
+}
+
+puts 'See you in a while...'
+Cromwell.protect {
+  sleep 10
+}
+puts "You're still here?"

data/lib/cromwell.rb

@@ -1,12 +1,44 @@
 class Cromwell
   DEFAULT_SIGNAL_LIST = %w[INT TERM HUP QUIT].freeze
 
-  @@logger      = nil
-  @@should_exit = false
-  @@protected   = false
-  @@old_traps   = {}
+  @logger       = nil
+  @should_exit  = false
+  @protected    = false
+  @old_traps    = {}
+  @custom_traps = {}
 
   class << self
+    # Something to log Cromwell's messages. This can be a +Logger+ or any other class that
+    # accepts +debug+ and +info+ messages. Default value is +nil+.
+    attr_accessor :logger
+
+    # True when the script will be terminated after protected block, i.e. when a signal
+    # was caught that was protected from. You can set it to false to prevent script from
+    # termination even if a signal was caught.
+    attr_accessor :should_exit
+    alias_method  :should_exit?, :should_exit
+
+    # True if the protection is currently active.
+    attr_reader  :protected
+    alias_method :protected?, :protected
+
+    # Use this +Hash+ to provide custom traps for signals while protection is active.
+    # The key should be a signal name (in same form as you give it to +protect+ method)
+    # and the value should be a +Proc+ object that will be called when appropriate
+    # signal is caught.
+    #
+    # Note that your block will replace default Cromwell's handler completely,
+    # so if you actually wanted to get the same behavior, you should use:
+    #
+    #  Cromwell.should_exit = true
+    #
+    # Example:
+    #
+    #   Cromwell.custom_traps["INT"] = proc {
+    #     puts "Trying your ^C skills, are you?"
+    #   }
+    attr_accessor :custom_traps
+
     # call-seq:
     #   Cromwell.protect(*signals) { ... some code ... }
     #   Cromwell.protect(*signals)
@@ -18,20 +50,12 @@ class Cromwell
     # 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
+    def protect *signals, &block
       debug "Protect called with [#{signals * ', '}]"
       set_up_traps(signals.empty? ? DEFAULT_SIGNAL_LIST : signals.flatten)
-      @@should_exit = false
-      @@protected   = true
-      if block_given?
-        begin
-          debug "About to yield to block."
-          yield
-          debug "After yielding to block."
-        ensure
-          unprotect
-        end
-      end
+      @should_exit = false
+      @protected   = true
+      protect_block(&block) if block_given?
     end
 
     # call-seq:
@@ -41,56 +65,14 @@ class Cromwell
     # 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
-      debug "Unprotect called"
-      @@protected = false
-      debug "should_exit? = #{@@should_exit}"
-      if @@should_exit
+      debug "Unprotect called, should_exit? = #{@should_exit}"
+      @protected = false
+      if @should_exit
         info "Exiting because should_exit is true"
         exit
+      else
+        restore_old_traps
       end
-      restore_old_traps
-    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.should_exit = boolean
-    #
-    # Set to false to prevent script from termination even if a signal was caught. You can also set
-    # this to true to have your script terminated after protected block should you wish so.
-    def should_exit= boolean
-      @@should_exit = boolean
-    end
-
-    # call-seq:
-    #   Cromwell.protected?
-    #
-    # True if the protection is currently active.
-    def protected?
-      @@protected
-    end
-
-    # call-seq:
-    #   Cromwell.logger
-    #
-    # Returns logger. There is no default logger, so if you haven't set this before, it will be nil.
-    def logger
-      @@logger
-    end
-
-    # call-seq:
-    #   Cromwell.logger = some_logger
-    #
-    # Set a logger for Cromwell.
-    def logger= logger
-      @@logger = logger
     end
 
   private
@@ -103,37 +85,50 @@ class Cromwell
 
     def set_up_trap signal
       debug "Setting trap for #{signal}"
-      trap signal do
-        if @@protected
-          info "Caught signal #{signal} -- ignoring."
-          @@should_exit = true
-          "IGNORE"
+      trap(signal) {
+        if @custom_traps.has_key? signal
+          @custom_traps[signal].call
         else
-          info "Caught signal #{signal} -- exiting."
-          exit
+          handle signal
         end
-      end
+      }
+    end
+
+    def handle signal
+      info "Caught signal #{signal} -- ignoring."
+      @should_exit = true
+      "IGNORE"
     end
 
     def stash old_trap, signal
       debug "Stashing old trap #{old_trap} for #{signal}"
-      @@old_traps[signal] = old_trap
+      @old_traps[signal] = old_trap
     end
 
     def restore_old_traps
-      @@old_traps.each do |signal, old_trap|
+      @old_traps.each do |signal, old_trap|
         debug "Restoring old trap #{old_trap} for #{signal}"
         trap signal, old_trap
       end
-      @@old_traps = {}
+      @old_traps = {}
     end
 
     def debug msg
-      @@logger.debug msg if @@logger
+      @logger.debug msg if @logger
     end
 
     def info msg
-      @@logger.info msg if @@logger
+      @logger.info msg if @logger
+    end
+
+    def protect_block &block
+      begin
+        debug "About to yield to block."
+        yield
+        debug "After yielding to block."
+      ensure
+        unprotect
+      end
     end
   end
 end

data/test/test_cromwell.rb

@@ -94,6 +94,24 @@ class TestCromwell < Test::Unit::TestCase
     end
   end
 
+  context "custom traps" do
+    should "be used if provided" do
+      im_in_ur_blok_touchin_ur_vars = false
+      Cromwell.custom_traps["HUP"] = proc {
+        im_in_ur_blok_touchin_ur_vars = true
+      }
+      Cromwell.protect {
+        Process.kill("HUP", $$)
+      }
+      assert im_in_ur_blok_touchin_ur_vars
+    end
+
+    teardown do
+      Cromwell.custom_traps = {}
+    end
+  end
+
+
   context "method protect" do
     should "set up trap with given signals" do
       Cromwell.expects(:set_up_traps).with(["HUP", "TERM"])
@@ -227,13 +245,8 @@ class TestCromwell < Test::Unit::TestCase
         Cromwell.logger = nil
       end
 
-      should "log about being called" do
-        @log.expects(:debug).with("Unprotect called")
-        Cromwell.unprotect
-      end
-
       should "log about should_exit value" do
-        @log.expects(:debug).with("should_exit? = false")
+        @log.expects(:debug).with("Unprotect called, should_exit? = false")
         Cromwell.unprotect
       end
     end # with a logger
@@ -247,4 +260,5 @@ class TestCromwell < Test::Unit::TestCase
     end
   end
 
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cromwell
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Przemyslaw Kowalczyk
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-14 00:00:00 +01:00
+date: 2010-01-31 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -55,6 +55,7 @@ files:
 - examples/example4.rb
 - examples/example5.rb
 - examples/example6.rb
+- examples/example7.rb
 - lib/cromwell.rb
 - test/helper.rb
 - test/test_cromwell.rb
@@ -95,3 +96,4 @@ test_files:
 - examples/example4.rb
 - examples/example5.rb
 - examples/example6.rb
+- examples/example7.rb