terminator 0.4.2 → 0.4.3

data/README

@@ -1,10 +1,48 @@
 NAME
-  terminator
+  Terminator
 
 SYNOPSIS
-  an external timeout mechanism based on processes and signals.  safe on
-  windows.  safe for system calls.  safe for minors.
-
+  An external timeout mechanism based on processes and signals.  Safe on
+  windows.  Safe for system calls.  Safe for minors.  but not very safe
+  for misbehaving, downtrodden zombied out processes.
+
+DESCRIPTION
+  Terminator is a solution to the problem of 'how am I meant to kill a
+  system call in Ruby!?'
+  
+  Ruby (at least MRI) uses green threads to "multitask".  This means that
+  there is really only ever one ruby process running which then splits up
+  it's processor time between all of it's threads internally.
+  
+  The processor then only has to deal with one ruby process and the ruby 
+  process deals with all it's threads.  There are pros and cons to this
+  method, but that is not the point of this library.
+  
+  The point is, that if you make a system call to an external resource from
+  ruby, then the kernel will go and make that call for ruby and NOT COME BACK
+  to ruby until that system call completes or fails.  This can take a very 
+  long time and is why your feeble attempts at using ruby's internal "Timeout"
+  command has failed miserably at timing out your external web service, database
+  or network connections.
+  
+  You see, Ruby just doesn't get a chance to do anything as the kernel goes
+  "I'm not going to talk to you again until your system calls complete". Sort
+  of a no win situation for Ruby.
+  
+  That's where Terminator comes in.  Like Arnie, he will come back.  No matter
+  what, and complete his mission, unless he gets aborted before his timeout,
+  you can trust Terminator to thoroughly and without remorse, nuke your 
+  misbehaving and timing out ruby processes efficiently, and quickly.
+
+HOW IT WORKS
+  Basically we create a new terminator ruby process, separate to the existing
+  running ruby process that has a simple command of sleep for x seconds, and then
+  do a process TERM on the PID of the original ruby process that created it.
+  
+  If your process finishes before the timeout, it will kill the Terminator first.
+  
+  So really it is a race of who is going to win?
+  
 INSTALL
   gem install terminator
 
@@ -14,7 +52,7 @@ URIS
 
 HISTORY
   0.4.2
-    initial version with
+    initial version
 
 AUTHORS
   ara.t.howard - ara.t.howard@gmail.com

data/lib/terminator.rb

@@ -4,13 +4,16 @@ require 'tempfile'
 require 'fattr'
 
 module Terminator
-  Version = '0.4.2'
+  Version = '0.4.3'
 
   def terminate options = {}, &block
-    options = { :seconds => Float(options).to_i } unless Hash === options 
+    options = { :seconds => Float(options).to_f } unless Hash === options 
 
     seconds = getopt :seconds, options
-    trap = getopt :trap, options, lambda{ eval("raise(::Terminator::Error, '#{ seconds }s')", block) }
+
+    raise ::Terminator::Error, "Time to kill must be greater than 0" unless seconds > 0
+
+    trap = getopt :trap, options, lambda{ eval("raise(::Terminator::Error, 'Timeout out after #{ seconds }s')", block) }
 
     handler = Signal.trap(signal, &trap)
 

data/spec/terminator_spec.rb

@@ -0,0 +1,135 @@
+#! /usr/bin/env bacon
+ 
+require 'rubygems'
+require 'bacon'
+
+alias :doing :lambda
+
+describe Terminator do
+  
+  describe "being given a contract to terminate" do
+    it "should not complain about it" do
+      doing { Terminator.terminate(1) { "Hello" } }.should_not raise_error
+    end
+    
+    it "should not accept an expired contract" do
+      doing { Terminator.terminate(0) { "Hello" } }.should.raise(Terminator::Error)
+    end
+    
+    it "should not accept a late contract" do
+      doing { Terminator.terminate(-0.1) { "Hello" } }.should.raise(Terminator::Error)
+    end
+    
+    it "should handle fractions of seconts" do
+      failed = false
+      Terminator.terminate(0.3) do
+        failed = true
+      end
+      failed.should.be.false
+    end
+
+  end
+
+  describe "handling contracts" do
+    it "should not kill it's mark if the mark completes" do
+      failed = false
+      Terminator.terminate(0.01) do
+        failed = true
+      end
+      failed.should.be.false
+    end
+
+    it "should not terminate it's mark until the time is up" do
+      failed = false
+      Terminator.terminate(1) do
+        sleep 0.9
+        failed = true
+      end
+      failed.should.be.false
+    end
+    
+    it "should handle multiple overlapping contracts gracefully" do
+      first_job  = false
+      second_job = false
+      third_job  = false
+
+      Terminator.terminate(0.3) do
+        first_job = true
+      end
+
+      Terminator.terminate(0.3) do
+        second_job = true
+      end
+
+      Terminator.terminate(0.3) do
+        third_job = true
+      end
+
+      first_job.should.be.true
+      second_job.should.be.true
+      third_job.should.be.true
+    end
+
+    it "should be a surgical weapon only selectively destroying it's marks" do
+      first_job  = false
+      second_job = false
+
+      begin
+        Terminator.terminate(0.3) do
+          sleep 0.4
+          first_job = true
+        end
+      rescue 
+        nil
+      end
+      
+      Terminator.terminate(0.3) do
+        second_job = true
+      end
+
+      first_job.should.be.false
+      second_job.should.be.true
+    end
+    
+    it "should a surgical weapon only selectively destroying it's marks - backwards" do
+      first_job  = false
+      second_job = false
+      
+      Terminator.terminate(0.3) do
+        first_job = true
+      end
+
+      begin
+        Terminator.terminate(0.3) do
+          sleep 0.4
+          second_job = true
+        end
+      rescue 
+        nil
+      end
+
+      first_job.should.be.true
+      second_job.should.be.false
+      
+    end
+    
+    it "should accept an optional trap handler" do
+      trap = lambda{ 'You failed me again!' }
+      
+      doing {
+        Terminator.terminate(0.001, :trap => trap) do
+          sleep 0.2
+          job = true
+        end }.should.raise(Terminator::Error)
+
+    end
+    
+  end
+
+end
+
+BEGIN {
+  rootdir = File.split(File.expand_path(File.dirname(File.dirname(__FILE__))))
+  libdir = File.join(rootdir, 'lib')
+  require File.join(libdir, 'terminator')
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: terminator
 version: !ruby/object:Gem::Version 
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors: 
 - Ara T. Howard
@@ -9,12 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-10 00:00:00 -06:00
+date: 2008-09-11 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: fattr
-  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -43,7 +42,8 @@ files:
 - samples/c.rb
 - samples/d.rb
 - spec
-- spec/terminator.rb
+- spec/terminator_spec.rb
+- terminator-0.4.2.gem
 has_rdoc: false
 homepage: http://codeforpeople.com/lib/ruby/terminator/
 post_install_message: 
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: codeforpeople
-rubygems_version: 1.2.0
+rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
 summary: terminator

data/spec/terminator.rb

@@ -1,16 +0,0 @@
-#! /usr/bin/env bacon
- 
-require 'rubygems'
-require 'bacon'
-
-describe Terminator do
-  it 'should have some tests' do
-    0b101010.should == 42
-  end
-end
-
-BEGIN {
-  rootdir = File.split(File.expand_path(File.dirname(File.dirname(__FILE__))))
-  libdir = File.join(rootdir, 'lib')
-  require File.join(libdir, 'terminator')
-}