timeout-interrupt 0.2.0 → 0.2.1

data/Gemfile

@@ -7,6 +7,7 @@ gem 'ffi-libc'
 group :development do
   gem "shoulda"
   gem "yard"
+	gem "redcarpet"
   gem "rdoc"
   gem "bundler"
   gem "jeweler"

data/Gemfile.lock

@@ -24,6 +24,7 @@ GEM
     rake (10.0.3)
     rdoc (4.0.0)
       json (~> 1.4)
+    redcarpet (2.2.2)
     shoulda (3.3.2)
       shoulda-context (~> 1.0.1)
       shoulda-matchers (~> 1.4.1)
@@ -45,6 +46,7 @@ DEPENDENCIES
   ffi-libc
   jeweler
   rdoc
+  redcarpet
   shoulda
   simplecov
   yard

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/timeout_interrupt.rb

@@ -1,40 +1,107 @@
 require 'ffi/libc'
 require 'timeout'
 
+# Provided by ffi-libc-lib and extended by this library, if needed.
+# Older version of ffi-libc does not provide {FFI::LibC.alarm}
 module FFI
 	module LibC
+		# @!method alarm(seconds)
+		# Sets an alarm. After `seconds` it will send an ALRM-signal to this process.
+		#
+		# Predefined alarm will be reset and will forget.
+		# @note Older implementations of ffi-libc does not provide {alarm}, but we need it.
+		#       So we detect, if it is not provided and attach it.
+		# @param seconds [0] Clears alarm.
+		# @param seconds [Integer] How many seconds should be waited, before ALRM-signal should be send?
+		# @return (nil)
 		attach_function :alarm, [:uint], :uint  unless FFI::LibC.respond_to? :alarm
 	end
 end
 
+# Helper module for `TimeoutInterrupt`
+# @see TimeoutInterrupt
 module TimeoutInterruptSingleton
 	class <<self
+		# Stores all timeouts.
+		#
+		# @param thread [nil] must be nil! Do not use it yet!
+		# @return [Hash< key(Integer): [at(Time), backtrace(Array<String>), exception(Exception)] >]
 		def timeouts thread = nil
-			@timeouts ||= Hash.new {|h,k| h[k] = [] }
-			thread = Thread.current  if thread.kind_of? Thread
+			@timeouts ||= Hash.new {|h,k| h[k] = {} }
+			thread = Thread.current  unless thread.kind_of? Thread
 			thread ? @timeouts[thread] : @timeouts
 		end
 
+		# If there's a timed out timeout, it will raise its exception.
+		# Can be used for handling ALRM-signal.
+		# It will prepare the next timeout, too.
+		#
+		# The timeout will not removed from timeouts, because it is timed out, yet.
+		# First, if timeout-scope will be exit, it will be removed.
+		#
+		# @return [nil]
 		def alarm_trap sig
+			raise_if_sb_timed_out
+			setup
+		end
+
+		# There is a timed out timeout? It will raise it!
+		# You need not to check it yourself, it will do it for you.
+		#
+		# @return [nil]
+		def raise_if_sb_timed_out
+			return  if self.timeouts.empty?
 			key, (at, bt, exception) = self.timeouts.min_by {|key,(at,bt,ex)| at }
 			return  if Time.now < at
 			raise exception, 'execution expired', bt
 		end
 
+		# Prepares the next timeout. Sets the trap and the shortest timeout as alarm.
+		#
+		# @return [nil]
 		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
+				raise_if_sb_timed_out
 				Signal.trap 'ALRM', &method( :alarm_trap)
-				FFI::LibC.alarm secs.to_i+1
+				key, (at, bt) = timeouts.min_by {|key,(at,bt)| at }
+				FFI::LibC.alarm (at - Time.now).to_i + 1
 			end
+			nil
 		end
 
-		def timeout seconds = nil, exception = nil
+		# Creates a timeout and calls your block, which has to finish before timeout occurs.
+		#
+		# @param seconds [Integer]     In `seconds` Seconds, it should raise a timeout, if not finished.
+		# @param seconds [nil]         Everything will be ignored and
+		#                             it will call {setup} for checking and preparing next known timeout.
+		# @param exception [Exception] which will be raised if timed out.
+		# @param exception [nil]       `TimeoutInterrupt::Error` will be used to raise.
+		# @param block [Proc]          Will be called and should finish its work before it timed out.
+		# @param block [nil]           Nothing will happen, instead it will return a Proc,
+		#                              which can be called with a block to use the timeout.
+		# @return If block given, the returned value of your block.
+		#         Or if not, it will return a Proc, which will expect a Proc if called.
+		#         This Proc has no arguments and will prepare a timeout, like if you had given a block.
+		#
+		# You can rescue `Timeout::Error`, instead `TimeoutInterrupt::Error`, it will work too.
+		#
+		# It will call your given block, which has `seconds` seconds to end.
+		# If you want to prepare a timeout, which should be used many times,
+		# without giving `seconds` and `exception`, you can omit the block,
+		# so, `TimeoutInterruptSingleton#timeout` will return a `Proc`, which want to have the block.
+		#
+		# There is a problem with scoped timeouts. If you rescue a timeout in an other timeout,
+		# it's possible, that the other timeout will never timeout, because both are timed out at once.
+		# Than you need to call `TimeoutInterruptSingleton#timeout` without arguments.
+		# It will prepare the next timeout or it will raise it directy, if timed out.
+		#
+		# @see TimeoutInterrupt.timeout
+		# @see TimeoutInterrupt#timeout
+		# @raise exception
+		def timeout seconds = nil, exception = nil, &block
 			return setup  if seconds.nil?
 			seconds = seconds.to_i
 			exception ||= TimeoutInterrupt::Error
@@ -59,15 +126,82 @@ module TimeoutInterruptSingleton
 	end
 end
 
+# Can be included, or used directly.
+# In both cases, it provides {#timeout}.
+#
+# @see TimeoutInterruptSingleton
 module TimeoutInterrupt
+	# The {TimeoutInterrupt::Error} is the default exception, which will be raised,
+	# if something will time out.
+	# Its base-class is {Timeout::Error}, so you can replace {Timeout} by {TimeoutInterrupt} without
+	# replacing your `rescue Timeout::Error`, but you can.
 	class Error < Timeout::Error
 	end
 
-	def self.timeout seconds = nil, exception = nil, &e
-		TimeoutInterruptSingleton.timeout seconds, exception, &e
+	# Creates a timeout and calls your block, which has to finish before timeout occurs.
+	#
+	# @param seconds [Integer]     In `seconds` Seconds, it should raise a timeout, if not finished.
+	# @param seconds [nil]         Everything will be ignored and
+	#     it will call {TimeoutInterruptSingleton.setup} for checking and preparing next known timeout.
+	# @param exception [Exception] which will be raised if timed out.
+	# @param exception [nil]       `TimeoutInterrupt::Error` will be used to raise.
+	# @param block [Proc]          Will be called and should finish its work before it timed out.
+	# @param block [nil]           Nothing will happen, instead it will return a Proc,
+	#                              which can be called with a block to use the timeout.
+	# @return If block given, the returned value of your block.
+	#         Or if not, it will return a Proc, which will expect a Proc if called.
+	#         This Proc has no arguments and will prepare a timeout, like if you had given a block.
+	#
+	# You can rescue `Timeout::Error`, instead `TimeoutInterrupt::Error`, it will work too.
+	#
+	# It will call your given block, which has `seconds` seconds to end.
+	# If you want to prepare a timeout, which should be used many times,
+	# without giving `seconds` and `exception`, you can omit the block,
+	# so, `TimeoutInterruptSingleton#timeout` will return a `Proc`, which want to have the block.
+	#
+	# There is a problem with scoped timeouts. If you rescue a timeout in an other timeout,
+	# it's possible, that the other timeout will never timeout, because both are timed out at once.
+	# Than you need to call `TimeoutInterruptSingleton#timeout` without arguments.
+	# It will prepare the next timeout or it will raise it directy, if timed out.
+	#
+	# @see TimeoutInterrupt#timeout
+	# @see TimeoutInterruptSingleton.timeout
+	# @raise exception
+	def self.timeout seconds = nil, exception = nil, &block
+		TimeoutInterruptSingleton.timeout seconds, exception, &block
 	end
 
-	def timeout seconds = nil, exception = nil, &e
-		TimeoutInterruptSingleton.timeout seconds, exception, &e
+	# Creates a timeout and calls your block, which has to finish before timeout occurs.
+	#
+	# @param seconds [Integer]     In `seconds` Seconds, it should raise a timeout, if not finished.
+	# @param seconds [nil]         Everything will be ignored and
+	#     it will call {TimeoutInterruptSingleton.setup} for checking and preparing next known timeout.
+	# @param exception [Exception] which will be raised if timed out.
+	# @param exception [nil]       `TimeoutInterrupt::Error` will be used to raise.
+	# @param block [Proc]          Will be called and should finish its work before it timed out.
+	# @param block [nil]           Nothing will happen, instead it will return a Proc,
+	#                              which can be called with a block to use the timeout.
+	# @return If block given, the returned value of your block.
+	#         Or if not, it will return a Proc, which will expect a Proc if called.
+	#         This Proc has no arguments and will prepare a timeout, like if you had given a block.
+	#
+	# You can rescue `Timeout::Error`, instead `TimeoutInterrupt::Error`, it will work too.
+	#
+	# It will call your given block, which has `seconds` seconds to end.
+	# If you want to prepare a timeout, which should be used many times,
+	# without giving `seconds` and `exception`, you can omit the block,
+	# so, `TimeoutInterruptSingleton#timeout` will return a `Proc`, which want to have the block.
+	#
+	# There is a problem with scoped timeouts. If you rescue a timeout in an other timeout,
+	# it's possible, that the other timeout will never timeout, because both are timed out at once.
+	# Than you need to call `TimeoutInterruptSingleton#timeout` without arguments.
+	# It will prepare the next timeout or it will raise it directy, if timed out.
+	#
+	# @note This method is useful, if you `include TimeoutInterrupt`. You can call it directly.
+	# @see TimeoutInterrupt.timeout
+	# @see TimeoutInterruptSingleton.timeout
+	# @raise exception
+	def timeout seconds = nil, exception = nil, &block
+		TimeoutInterruptSingleton.timeout seconds, exception, &block
 	end
 end

data/timeout-interrupt.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "timeout-interrupt"
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Denis Knauf"]
@@ -42,6 +42,7 @@ Gem::Specification.new do |s|
       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<redcarpet>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, [">= 0"])
       s.add_development_dependency(%q<bundler>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, [">= 0"])
@@ -50,6 +51,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<ffi-libc>, [">= 0"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<redcarpet>, [">= 0"])
       s.add_dependency(%q<rdoc>, [">= 0"])
       s.add_dependency(%q<bundler>, [">= 0"])
       s.add_dependency(%q<jeweler>, [">= 0"])
@@ -59,6 +61,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<ffi-libc>, [">= 0"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<redcarpet>, [">= 0"])
     s.add_dependency(%q<rdoc>, [">= 0"])
     s.add_dependency(%q<bundler>, [">= 0"])
     s.add_dependency(%q<jeweler>, [">= 0"])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeout-interrupt
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2013-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi-libc
-  requirement: &79897400 !ruby/object:Gem::Requirement
+  requirement: &78508080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *79897400
+  version_requirements: *78508080
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &79918180 !ruby/object:Gem::Requirement
+  requirement: &78507820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79918180
+  version_requirements: *78507820
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &79914220 !ruby/object:Gem::Requirement
+  requirement: &78507570 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,21 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79914220
+  version_requirements: *78507570
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &78507280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *78507280
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &79910520 !ruby/object:Gem::Requirement
+  requirement: &78506950 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79910520
+  version_requirements: *78506950
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &79907200 !ruby/object:Gem::Requirement
+  requirement: &78505780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79907200
+  version_requirements: *78505780
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &79905270 !ruby/object:Gem::Requirement
+  requirement: &78505320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79905270
+  version_requirements: *78505320
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &79904230 !ruby/object:Gem::Requirement
+  requirement: &78505050 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +98,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79904230
+  version_requirements: *78505050
 description: Timeout-lib, which interrupts everything, also systemcalls. It uses libc-alarm.
 email: Denis.Knauf@gmail.com
 executables: []
@@ -122,7 +133,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -567688307
+      hash: -241597663
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: