timeout-interrupt 0.1.1 → 0.2.0

data/README.md

@@ -7,9 +7,62 @@ It uses POSIX's alarm and traps ALRM-signals.
 
 Known limitations bacause of alarm and ALRM are, that you can not use alarm or trap ALRM.
 
+Scopes
+======
+
+If you need scopes with inner and outer time outs, you should know:
+
+The first timed out Timeout will be raised:
+
+	include TimeoutInterrupt
+	timeout(1) { # Will be raised
+		timeout(10) { sleep 2 } # Will not be raised
+	}
+
+If you want to know, which was raised, you need custom exceptions:
+
+	class CustomErrorWillBeRaised <Exception
+	end
+	class CustomErrorNotRaise <Exception
+	end
+	include TimeoutInterrupt
+	timeout( 1, CustomErrorWillBeRaised) { # Will be raised again
+		timeout( 10, CustomErrorNotRaise) { sleep 2 } # Will not be raised
+	}
+
+Problems
+========
+
+Memory-Leaks or no clean up
+---------------------------
+
 Do not forget, syscall can have allocated memory.
 If you interrupt a call, which can not free his allocations, you will have a memory leak.
-So, use it only, if your process did not live any longer or if you call something, which never allocate mem
+If it opens a file, reads it and closes it and while it reads, a time out occurs, the file will not be closed.
+
+So, use it only, if your process did not live any longer or if you call something, which never allocate mem or opens a file.
+
+Every time, a process dies, all his memory will be freed and every file will be closed, so let your process die and you should be safe.
+
+Exception-handling
+------------------
+
+Timeouts can break your exception-handling! You should not handling exception while you wait for a timeout:
+
+	include TimeoutInterrupt
+	timeout(1) {
+		begin
+			transaction_begin
+			do_something
+		ensure
+			clean_up
+			transaction_end
+		end
+	}
+
+Same happens, if clean\_up will raise an exception.
+
+And same problem you have with ruby's `Timeout.timeout`.
 
 Copyleft
 =========

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/timeout_interrupt.rb

@@ -7,43 +7,67 @@ module FFI
 	end
 end
 
-module TimeoutInterrupt
-	def self.timeouts
-		@timeouts ||= {}
+module TimeoutInterruptSingleton
+	class <<self
+		def timeouts thread = nil
+			@timeouts ||= Hash.new {|h,k| h[k] = [] }
+			thread = Thread.current  if thread.kind_of? Thread
+			thread ? @timeouts[thread] : @timeouts
+		end
+
+		def alarm_trap sig
+			key, (at, bt, exception) = self.timeouts.min_by {|key,(at,bt,ex)| at }
+			return  if Time.now < at
+			raise exception, 'execution expired', bt
+		end
+
+		def setup
+			if timeouts.empty?
+				Signal.trap( 'ALRM') {}
+				FFI::LibC.alarm 0
+			else
+				key, (at, bt) = timeouts.min_by {|key,(at,bt)| at }
+				secs = (at - Time.now)
+				alarm_trap 14  if 0 > secs
+				Signal.trap 'ALRM', &method( :alarm_trap)
+				FFI::LibC.alarm secs.to_i+1
+			end
+		end
+
+		def timeout seconds = nil, exception = nil
+			return setup  if seconds.nil?
+			seconds = seconds.to_i
+			exception ||= TimeoutInterrupt::Error
+			raise exception, "Timeout must be longer than '0' seconds."  unless 0 < seconds
+			unless block_given?
+				return lambda {|&e|
+					raise exception, "Expect a lambda."  unless e
+					timeout seconds, exception, &e
+				}
+			end
+			at = Time.now + seconds
+			key, bt = Random.rand( 2**64-1), Kernel.caller
+			begin
+				self.timeouts[key] = [at, bt, exception]
+				setup
+				yield
+			ensure
+				self.timeouts.delete key
+				setup
+			end
+		end
 	end
+end
 
-	def self.alarm_trap sig
-		key, (at, bt) = TimeoutInterrupt.timeouts.min_by {|key,(at,bt)| at }
-		return  if Time.now < at
-		raise Timeout::Error, 'execution expired', bt
+module TimeoutInterrupt
+	class Error < Timeout::Error
 	end
 
-	def self.setup_timeout
-		if TimeoutInterrupt.timeouts.empty?
-			Signal.trap( 'ALRM') {}
-			FFI::LibC.alarm 0
-		else
-			key, (at, bt) = TimeoutInterrupt.timeouts.min_by {|key,(at,bt)| at }
-			secs = (at - Time.now).to_i+1
-			TimeoutInterrupt.alarm_trap  if 1 > secs
-			Signal.trap 'ALRM', &TimeoutInterrupt.method( :alarm_trap)
-			FFI::LibC.alarm secs
-		end
+	def self.timeout seconds = nil, exception = nil, &e
+		TimeoutInterruptSingleton.timeout seconds, exception, &e
 	end
 
-	def self.timeout seconds
-		seconds = seconds.to_i
-		raise Timeout::Error, "Timeout must be longer than '0' seconds."  unless 0 < seconds
-		return lambda {|&e| self.timeout seconds, &e }  unless block_given?
-		at = Time.now + seconds
-		key, bt = Random.rand( 2**64-1), Kernel.caller
-		begin
-			TimeoutInterrupt.timeouts[key] = [at, bt]
-			TimeoutInterrupt.setup_timeout
-			yield
-		ensure
-			TimeoutInterrupt.timeouts.delete key
-			TimeoutInterrupt.setup_timeout
-		end
+	def timeout seconds = nil, exception = nil, &e
+		TimeoutInterruptSingleton.timeout seconds, exception, &e
 	end
 end

data/test/test_ruby-timeout-interrupt.rb

@@ -11,70 +11,145 @@ class TestRubyTimeoutInterrupt < Test::Unit::TestCase
 	end
 
 	def assert_no_defined_timeout_yet
-		assert TimeoutInterrupt.timeouts.empty?, "For testing, no timeout should be defined, yet!"
+		assert TimeoutInterruptSingleton.timeouts.empty?, "For testing, no timeout should be defined, yet!"
 	end
 
-	should "not interrupt a long blocking call with the old Timeout" do
-		time = Benchmark.realtime do
-			begin
-				TimeoutInterrupt.timeout(5) do
-					Timeout.timeout(1) do
-						blocking
-						assert false, "Should be unreachable!"
+	def print_timeouts pre
+		puts "#{pre}: < #{TimeoutInterruptSingleton.timeouts.map {|k,(a,_b,_e)| "#{k.inspect}: #{a.strftime '%H:%M:%S'} (#{a-Time.now})" }.join ', '} >"
+	end
+
+	# For testing raising scoped Timeout.
+	class TimeoutError < Exception
+	end
+	# For testing raising scoped TimeoutInterrupt.
+	class TimeoutInterruptError < Exception
+	end
+
+	context "Long really blocking calls" do
+		should "not be interrupted by the old Timeout" do
+			time = Benchmark.realtime do
+				assert_nothing_raised TimeoutError, "Unexpected time out. Your Ruby implementation can time out with old Timeout? You need not TimeoutInterrupt. But it is ok. You can ignore this Error. :)" do
+					assert_raise TimeoutInterruptError, "Ohoh. TimeoutInterrupt should be raised." do
+						TimeoutInterrupt.timeout 5, TimeoutInterruptError do
+							Timeout.timeout 1, TimeoutError do
+								blocking
+								assert false, "Should be unreachable!"
+							end
+						end
 					end
 				end
-			rescue Timeout::Error
-				:ok
 			end
+			assert 3 < time, "Did timeout!"
 		end
-		assert 3 < time, "Did timeout!"
-	end
 
-	should "interrupt a long blocking call with the new TimeoutInterrupt" do
-		time = Benchmark.realtime do
-			begin
-				TimeoutInterrupt.timeout(1) do
-					blocking
-					assert false, "Should be unreachable!"
+		should "be interrupted by the new TimeoutInterrupt" do
+			time = Benchmark.realtime do
+				assert_raise TimeoutInterrupt::Error, "It should be timed out, why it did not raise TimeoutInterrupt::Error?" do
+					TimeoutInterrupt.timeout 1 do
+						blocking
+						assert false, "Should be unreachable!"
+					end
 				end
-			rescue Timeout::Error
-				:ok
 			end
+			assert 3 > time, "Did not interrupt."
 		end
-		assert 3 > time, "Did not interrupt."
 	end
 
-	should "interrupt scoped timeout, but not outer timeout" do
+	should "interrupt scoped timeout, but not time out the outer timeout" do
 		assert_no_defined_timeout_yet
-		begin
-			TimeoutInterrupt.timeout(10) do
-				TimeoutInterrupt.timeout(1) do
-					Kernel.sleep 2
+		assert_raise TimeoutInterruptError, "It should be timed out, why it did not raise TimeoutInterruptError?" do
+			assert_nothing_raised Timeout::Error, "Oh, outer timeout was timed out. Your machine must be slow, or there is a bug" do
+				TimeoutInterrupt.timeout 10 do
+					TimeoutInterrupt.timeout 1, TimeoutInterruptError do
+						Kernel.sleep 2
+					end
+					assert false, "Should be unreachable!"
 				end
-				assert false, "Should be unreachable!"
 			end
-		rescue Timeout::Error
-			:ok
 		end
-		assert TimeoutInterrupt.timeouts.empty?, "There are timeouts defined, yet!"
+		assert TimeoutInterruptSingleton.timeouts.empty?, "There are timeouts defined, yet!"
 	end
 
 	should "clear timeouts, if not timed out, too." do
 		assert_no_defined_timeout_yet
 		TimeoutInterrupt.timeout(10) {}
-		assert TimeoutInterrupt.timeouts.empty?, "There are timeouts defined, yet!"
+		assert TimeoutInterruptSingleton.timeouts.empty?, "There are timeouts defined, yet!"
 	end
 
-	should "return a Proc if now block given, but do not create a timeout." do
-		assert_no_defined_timeout_yet
-		assert TimeoutInterrupt.timeout(10).kind_of?( Proc), "Did not return a Proc."
+	class CustomException <Exception
 	end
 
-	should "run a returned Proc with given timeout." do
-		assert_no_defined_timeout_yet
-		to = TimeoutInterrupt.timeout(10)
-		called = false
-		to.call { called = true }
-		assert called, "Did not called."
+	should "raise custom exception." do
+		assert_raise CustomException, "Custom exceptions do not work." do
+			TimeoutInterrupt.timeout 1, CustomException do
+				sleep 2
+			end
+		end
+	end
+
+	context "A prepared timeout (Proc)" do
+		should "be returned by calling timeout without a block" do
+			assert_no_defined_timeout_yet
+			assert TimeoutInterrupt.timeout(10).kind_of?( Proc), "Did not return a Proc."
+		end
+
+		should "run with once given timeout" do
+			assert_no_defined_timeout_yet
+			to = TimeoutInterrupt.timeout 10
+			called = false
+			to.call { called = true }
+			assert called, "Did not called."
+		end
+
+		should "raise custom exception" do
+			assert_raise CustomException, "Custom exceptions do not work." do
+				prepared = TimeoutInterrupt.timeout 1, CustomException
+				prepared.call { sleep 2 }
+			end
+		end
+
+		should "not be scopeable, without manualy setup after rescue and 2 time outs at once" do
+			prepared = TimeoutInterrupt.timeout 1
+			assert_no_defined_timeout_yet
+			called = false
+			prepared.call do
+				assert_raise TimeoutInterrupt::Error, 'It should time out after one second, but it did not.' do
+					prepared.call { 2; sleep 2 }
+				end
+				called = true
+			end
+			assert called, "It's true, it should be called, also if not expected."
+		end
+
+		should "be scopeable, with manualy setup after rescue, also if 2 time outs at once." do
+			prepared = TimeoutInterrupt.timeout 1
+			assert_no_defined_timeout_yet
+			prepared.call do
+				assert_raise TimeoutInterrupt::Error, 'It should time out after one second, but it did not.' do
+					prepared.call { sleep 2 }
+				end
+				assert_raise TimeoutInterrupt::Error, 'Manualy called timeout setup did not raise.' do
+					TimeoutInterrupt.timeout
+				end
+				assert true, "Should never be reached."
+			end
+		end
+	end
+
+	class IncludeModuleTest
+		include TimeoutInterrupt
+		def please_timeout after
+			timeout after do
+				sleep after+10
+			end
+		end
+	end
+
+	context "Included module" do
+		should "provide timeout too" do
+			assert_raise TimeoutInterrupt::Error, "Included timeout can not be used?" do
+				IncludeModuleTest.new.please_timeout 2
+			end
+		end
 	end
 end

data/timeout-interrupt.gemspec

@@ -0,0 +1,68 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "timeout-interrupt"
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Denis Knauf"]
+  s.date = "2013-03-07"
+  s.description = "Timeout-lib, which interrupts everything, also systemcalls. It uses libc-alarm."
+  s.email = "Denis.Knauf@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/timeout_interrupt.rb",
+    "test/helper.rb",
+    "test/test_ruby-timeout-interrupt.rb",
+    "timeout-interrupt.gemspec"
+  ]
+  s.homepage = "http://github.com/DenisKnauf/ruby-timeout-interrupt"
+  s.licenses = ["AGPLv3"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.11"
+  s.summary = "\"Interrupts systemcalls too.\""
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ffi-libc>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+    else
+      s.add_dependency(%q<ffi-libc>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<ffi-libc>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<rdoc>, [">= 0"])
+    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeout-interrupt
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-06 00:00:00.000000000 Z
+date: 2013-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi-libc
-  requirement: &72349180 !ruby/object:Gem::Requirement
+  requirement: &79897400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *72349180
+  version_requirements: *79897400
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &72348250 !ruby/object:Gem::Requirement
+  requirement: &79918180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72348250
+  version_requirements: *79918180
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &72367400 !ruby/object:Gem::Requirement
+  requirement: &79914220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72367400
+  version_requirements: *79914220
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &72364150 !ruby/object:Gem::Requirement
+  requirement: &79910520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72364150
+  version_requirements: *79910520
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &72360610 !ruby/object:Gem::Requirement
+  requirement: &79907200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72360610
+  version_requirements: *79907200
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &72357200 !ruby/object:Gem::Requirement
+  requirement: &79905270 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72357200
+  version_requirements: *79905270
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &72355990 !ruby/object:Gem::Requirement
+  requirement: &79904230 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *72355990
+  version_requirements: *79904230
 description: Timeout-lib, which interrupts everything, also systemcalls. It uses libc-alarm.
 email: Denis.Knauf@gmail.com
 executables: []
@@ -106,6 +106,7 @@ files:
 - lib/timeout_interrupt.rb
 - test/helper.rb
 - test/test_ruby-timeout-interrupt.rb
+- timeout-interrupt.gemspec
 homepage: http://github.com/DenisKnauf/ruby-timeout-interrupt
 licenses:
 - AGPLv3
@@ -121,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -502487251
+      hash: -567688307
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: