cromwell 0.2.0 → 0.3.0

data/README.rdoc

@@ -175,6 +175,37 @@ When run, it goes like this:
 
 Of course, had I press <code>^C</code> right after "See you in a while...", the script would terminate after 1 second at the end of the protected block.
 
+=== Logging
+
+If want to see what is going on with Cromwell or have some problems with it, you can use a logger (requires cromwell gem version >= 0.3). If Cromwell is used inside an application that already uses logging, you can use your app's logger. Or you might prefer to use a separate logger.
+
+Cromwell uses two levels of log messages:
+
+* <code>Logger::INFO</code> -- when a signal was caught or script is terminated.
+* <code>Logger::DEBUG</code> -- all sorts of debugging information: setting up and restoring traps, calling methods and yielding block. Probably not useful for you, unless you have some problems with Cromwell or are messing with the code.
+
+Here's an example of logger usage:
+
+  Cromwell.logger = Logger.new(STDOUT)
+  Cromwell.logger.level = Logger::INFO
+
+  puts 'See you in a while...'
+  Cromwell.protect {
+    sleep 10
+  }
+  puts "You're still here?"
+
+When run, this script will log messages on <code>STDOUT</code>:
+
+  $ ruby examples/example6.rb
+  See you in a while...
+  ^CI, [2010-01-14T11:59:29.246851 #19011]  INFO -- : Caught signal INT -- ignoring.
+  ^CI, [2010-01-14T11:59:31.558532 #19011]  INFO -- : Caught signal INT -- ignoring.
+  ^CI, [2010-01-14T11:59:36.270395 #19011]  INFO -- : Caught signal INT -- ignoring.
+  [ ten seconds pass... ]
+  I, [2010-01-14T11:59:37.872514 #19011]  INFO -- : Exiting because should_exit is true
+  $
+
 == 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).
@@ -182,10 +213,13 @@ Works for me. Tested on Mac OS X 10.4--10.6 and a little bit on Debian Linux. If
 == 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).
-* Add logger support.
 
 == Changelog
 
+=== 0.3
+
+* Added logger support.
+
 === 0.2
 
 * Remove traps when they are not needed anymore and restore original traps.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/cromwell.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cromwell}
-  s.version = "0.2.0"
+  s.version = "0.3.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-08}
+  s.date = %q{2010-01-14}
   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 = [
@@ -29,6 +29,7 @@ Gem::Specification.new do |s|
      "examples/example3.rb",
      "examples/example4.rb",
      "examples/example5.rb",
+     "examples/example6.rb",
      "lib/cromwell.rb",
      "test/helper.rb",
      "test/test_cromwell.rb"
@@ -45,7 +46,8 @@ Gem::Specification.new do |s|
      "examples/example2.rb",
      "examples/example3.rb",
      "examples/example4.rb",
-     "examples/example5.rb"
+     "examples/example5.rb",
+     "examples/example6.rb"
   ]
 
   if s.respond_to? :specification_version then

data/examples/example6.rb

@@ -0,0 +1,14 @@
+# 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'
+require 'logger'
+
+Cromwell.logger = Logger.new(STDOUT)
+Cromwell.logger.level = Logger::INFO
+
+puts 'See you in a while...'
+Cromwell.protect {
+  sleep 10
+}
+puts "You're still here?"

data/lib/cromwell.rb

@@ -1,6 +1,11 @@
 class Cromwell
   DEFAULT_SIGNAL_LIST = %w[INT TERM HUP QUIT].freeze
 
+  @@logger      = nil
+  @@should_exit = false
+  @@protected   = false
+  @@old_traps   = {}
+
   class << self
     # call-seq:
     #   Cromwell.protect(*signals) { ... some code ... }
@@ -14,12 +19,15 @@ class Cromwell
     # Without parameters, the code is protected from the signals in DEFAULT_SIGNAL_LIST.
     # More info and examples in README.rdoc.
     def protect *signals
+      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
@@ -33,8 +41,13 @@ 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
-      exit if @@should_exit
+      debug "should_exit? = #{@@should_exit}"
+      if @@should_exit
+        info "Exiting because should_exit is true"
+        exit
+      end
       restore_old_traps
     end
 
@@ -64,33 +77,63 @@ class Cromwell
       @@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
     def set_up_traps signals
-      signals.each { |signal| set_up_trap signal }
+      signals.each do |signal|
+        old_trap = set_up_trap signal
+        stash old_trap, signal
+      end
     end
 
     def set_up_trap signal
-      old_trap = trap signal do
+      debug "Setting trap for #{signal}"
+      trap signal do
         if @@protected
+          info "Caught signal #{signal} -- ignoring."
           @@should_exit = true
           "IGNORE"
         else
+          info "Caught signal #{signal} -- exiting."
           exit
         end
       end
-      stash old_trap, signal
     end
 
     def stash old_trap, signal
-      @@old_traps ||= {}
+      debug "Stashing old trap #{old_trap} for #{signal}"
       @@old_traps[signal] = old_trap
     end
 
     def restore_old_traps
       @@old_traps.each do |signal, old_trap|
+        debug "Restoring old trap #{old_trap} for #{signal}"
         trap signal, old_trap
       end
       @@old_traps = {}
     end
+
+    def debug msg
+      @@logger.debug msg if @@logger
+    end
+
+    def info msg
+      @@logger.info msg if @@logger
+    end
   end
 end

data/test/test_cromwell.rb

@@ -115,9 +115,52 @@ class TestCromwell < Test::Unit::TestCase
       assert Cromwell.protected?
     end
 
+    context "with a logger" do
+      setup do
+        @log = stub :debug => true
+        Cromwell.logger = @log
+      end
+
+      teardown do
+        Cromwell.logger = nil
+      end
+
+      should "log about being called" do
+        @log.expects(:debug).with("Protect called with []")
+        Cromwell.protect { i = 1 }
+      end
+
+      should "log about being called with parameters" do
+        @log.expects(:debug).with("Protect called with [HUP, TERM]")
+        Cromwell.protect("HUP", "TERM") { i = 1 }
+      end
+
+      should "log about setting traps" do
+        @log.expects(:debug).with("Setting trap for HUP")
+        @log.expects(:debug).with("Setting trap for TERM")
+        Cromwell.protect("HUP", "TERM") { i = 1 }
+      end
+
+      should "log about stashing old traps" do
+        Signal.trap "HUP", proc {}
+        Signal.trap "TERM", "DEFAULT"
+        @log.expects(:debug).with(regexp_matches(/^Stashing old trap #<Proc:.+> for HUP$/))
+        @log.expects(:debug).with('Stashing old trap DEFAULT for TERM')
+        Cromwell.protect("HUP", "TERM") { i = 1 }
+      end
+
+      should "log about restoring old traps" do
+        Signal.trap "HUP", proc {}
+        Signal.trap "TERM", "DEFAULT"
+        @log.expects(:debug).with(regexp_matches(/^Restoring old trap #<Proc:.+> for HUP$/))
+        @log.expects(:debug).with('Restoring old trap DEFAULT for TERM')
+        Cromwell.protect("HUP", "TERM") { i = 1 }
+      end
+    end # with a logger
+
   end # method protect
 
-  context "method protect with block" do
+  context "method protect with a block" do
     should "yield to block" do
       im_in_ur_blok_touchin_ur_vars = false
       Cromwell.protect {
@@ -136,6 +179,28 @@ class TestCromwell < Test::Unit::TestCase
         assert Cromwell.protected?
       }
     end
+
+    context "with a logger" do
+      setup do
+        @log = stub :debug => true
+        Cromwell.logger = @log
+      end
+
+      teardown do
+        Cromwell.logger = nil
+      end
+
+      should "log before yield" do
+        @log.expects(:debug).with('About to yield to block.')
+        Cromwell.protect { i = 1 }
+      end
+
+      should "log after yield" do
+        @log.expects(:debug).with('After yielding to block.')
+        Cromwell.protect { i = 1 }
+      end
+    end # with a logger
+
   end # method protect with block
 
   context "method unprotect" do
@@ -150,6 +215,28 @@ class TestCromwell < Test::Unit::TestCase
       Cromwell.expects(:exit)
       Cromwell.unprotect
     end
+
+    context "with a logger" do
+      setup do
+        @log = stub :debug => true
+        Cromwell.logger = @log
+        Cromwell.should_exit = false
+      end
+
+      teardown do
+        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")
+        Cromwell.unprotect
+      end
+    end # with a logger
   end # method unprotect
 
   context "should_exit=" do

metadata

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