much-timeout 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 --- 
-SHA1: 
-  metadata.gz: bb4cac19b782d0ee31fd1fd5f00134a8aa6945df
-  data.tar.gz: 0da45180c2d2a786d818ef1dfd00a4bd20805bfb
 SHA512: 
-  metadata.gz: c3d83151e871821b5cbebbea52693074c305b746e0f1b5e5bc62909913a5966d9d55605869a98a52ce5f4d0f054ccc0918f91194cfee9010c352fd1138313ffd
-  data.tar.gz: 18c841613cd442bab3aefd9e2881c3630bf98de6da287382fddfa976e8401a43e21b868abc13094ad99f36d80c702b1b0235c09725242996cea82f1a0a99a69f
+  data.tar.gz: 2fa361b98af1eaae451ed91a28d1d9641777eab828716d4c10a3411170f0bc6de3dc8f4c3855b368a2e29badcb23f8082b4d4b237fa89af72c4660a585a80263
+  metadata.gz: 265aaee5763dc7fc6d5208ea42ceefb11dc8cfeb5f70173885c0bd0206ff41dcbe405d9c233b2d6948f72e21d6a1fb9506333852be349c81841db08a2a050afd
+SHA1: 
+  data.tar.gz: 0bbfd0ebdc797ec310f8bc33f39e40a51973e4b5
+  metadata.gz: 3239b0fddda2d296afeab424878e399219bf5fa7

data/README.md

@@ -1,10 +1,85 @@
 # MuchTimeout
 
-IO.select based timeouts
+IO.select based timeouts.  This is an alternative to the stdlib's Timeout module that doesn't rely on `sleep`.  This should produce more accurate timeouts with an expanded API for different handling options.
 
 ## Usage
 
-TODO: Write code samples and usage instructions here
+### `timeout`
+
+```ruby
+require 'much-timeout'
+
+MuchTimeout.timeout(5) do
+  # ... something that should be interrupted ...
+
+  # raises a `MuchTimeout::TimeoutError` exception if it takes more than 5 seconds
+  # returns the result of the block otherwise
+end
+```
+
+MuchTimeout, in its basic form, is a replacement for Timeout.  The main difference is that `IO.select` on an internal pipe is the mechanism for detecting the timeout.  Another difference is that the block is executed in a separate thread while the select/monitoring occurs in the main thread.
+
+**Note**: like Timeout, **`Thread#raise` is used to interrupt the block**.  This technique is [widely](http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html) [considered](http://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/) to be [dangerous](http://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/).  Be aware and use responsibly.
+
+```ruby
+MuchTimeout.timeout(5, MyCustomTimeoutError) do
+  # ... something that should be interrupted ...
+
+  # raises a `MyCustomTimeoutError` exception if it takes more than 5 seconds
+end
+```
+
+Like Timeout, you can optionally specify a custom exception class to raise.
+
+### `optional_timeout`
+
+```ruby
+seconds = [5, nil].sample
+MuchTimeout.optional_timeout(seconds) do
+  # ... something that should be interrupted ...
+
+  # raises an exception if seconds is not nil and it takes more than 5 seconds
+  # otherwise the block is called directly and will not be interrupted
+end
+```
+
+In addtion to the basic `timeout` API, MuchTimeout provides `optional_timeout` which conditionally applies timeout handling based on the given seconds value.  Passing `nil` seconds will just call the block and will not apply any timeout handling (where passing `nil` seconds to `timeout` raises an argument error).
+
+### `just_{optional_}timeout`
+
+```ruby
+MuchTimeout.just_timeout(5, :do => proc{
+  # ... something that should be interrupted ...
+
+  # interrupt if it takes more than 5 seconds
+  # no exceptions are raised (they are all rescued internally)
+})
+
+seconds = [5, nil].sample
+MuchTimeout.just_optional_timeout(seconds, :do => proc{
+  # ... something that should be interrupted ...
+
+  # interrupt if seconds is not nil and it takes more than 5 seconds
+  # no exceptions are raised (they are all rescued internally)
+})
+```
+
+These alternative timeout methods execute and interrupt the given `:do` block if it times out.  However, no exceptions are raised and no exception handling is required (the `Thread#raise` interrupt is rescued internally).  Use this option to avoid any custom exception handling logic when you don't care about the timeout exception information.
+
+In the case you want to run some custom logic when a timeout occurs, pass an optional `:on_timeout` proc:
+
+```ruby
+MuchTimeout.just_timeout(5, {
+  :do => proc{
+    # ... something that should be interrupted ...
+  },
+  :on_timeout => proc{
+    # ... something that should run when a timeout occurs ...
+  }
+})
+```
+
+This works as you'd expect for both `just_timeout` and `just_optional_timeout`.
 
 ## Installation
 

data/lib/much-timeout.rb

@@ -1,4 +1,88 @@
+require 'thread'
 require "much-timeout/version"
 
 module MuchTimeout
+
+  TimeoutError = Class.new(Interrupt)
+
+  PIPE_SIGNAL = '.'
+
+  def self.timeout(seconds, klass = nil, &block)
+    if seconds.nil?
+      raise ArgumentError, 'please specify a non-nil seconds value'
+    end
+    if !seconds.kind_of?(::Numeric)
+      raise ArgumentError, "please specify a numeric seconds value " \
+                           "(`#{seconds.inspect}` was given)"
+    end
+    exception_klass = klass || TimeoutError
+    reader, writer  = IO.pipe
+
+    begin
+      block_thread ||= Thread.new do
+        begin
+          block.call
+        ensure
+          writer.write_nonblock(PIPE_SIGNAL) rescue false
+        end
+      end
+      if !!::IO.select([reader], nil, nil, seconds)
+        block_thread.join
+      else
+        block_thread.raise exception_klass
+        block_thread.join
+      end
+      block_thread.value
+    ensure
+      reader.close rescue false
+      writer.close rescue false
+    end
+  end
+
+  def self.optional_timeout(seconds, klass = nil, &block)
+    if !seconds.nil?
+      self.timeout(seconds, klass, &block)
+    else
+      block.call
+    end
+  end
+
+  def self.just_timeout(seconds, args)
+    args ||= {}
+    if args[:do].nil?
+      raise ArgumentError, 'you need to specify a :do block arg to call'
+    end
+    if !args[:do].kind_of?(::Proc)
+      raise ArgumentError, "you need pass a Proc as the :do arg " \
+                           "(`#{args[:do].inspect}` was given)"
+    end
+    if !args[:on_timeout].nil? && !args[:on_timeout].kind_of?(::Proc)
+      raise ArgumentError, "you need pass a Proc as the :on_timeout arg " \
+                           "(`#{args[:on_timeout].inspect}` was given)"
+    end
+
+    begin
+      self.timeout(seconds, &args[:do])
+    rescue TimeoutError
+      (args[:on_timeout] || proc{ }).call
+    end
+  end
+
+  def self.just_optional_timeout(seconds, args)
+    args ||= {}
+    if args[:do].nil?
+      raise ArgumentError, 'you need to specify a :do block arg to call'
+    end
+    if !args[:do].kind_of?(::Proc)
+      raise ArgumentError, "you need pass a Proc as the :do arg " \
+                           "(`#{args[:do].inspect}` was given)"
+    end
+
+    if !seconds.nil?
+      self.just_timeout(seconds, args)
+    else
+      args[:do].call
+    end
+  end
+
 end

data/lib/much-timeout/version.rb

@@ -1,3 +1,3 @@
 module MuchTimeout
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/much-timeout.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version     = MuchTimeout::VERSION
   gem.authors     = ["Kelly Redding", "Collin Redding"]
   gem.email       = ["kelly@kellyredding.com", "collin.redding@me.com"]
-  gem.summary     = "IO.select based timeouts"
-  gem.description = "IO.select based timeouts"
+  gem.summary     = "IO.select based timeouts; an alternative to Ruby's stdlib Timeout module."
+  gem.description = "IO.select based timeouts; an alternative to Ruby's stdlib Timeout module."
   gem.homepage    = "http://github.com/redding/much-timeout"
   gem.license     = 'MIT'
 

data/test/unit/much-timeout_tests.rb

@@ -0,0 +1,322 @@
+require 'assert'
+require 'much-timeout'
+
+module MuchTimeout
+
+  class UnitTests < Assert::Context
+    desc "MuchTimeout"
+    setup do
+      @module = MuchTimeout
+    end
+    subject{ @module }
+
+    should have_imeths :timeout, :optional_timeout
+    should have_imeths :just_timeout, :just_optional_timeout
+
+    should "know its TimeoutError" do
+      assert_true subject::TimeoutError < Interrupt
+    end
+
+    should "know its pipe signal" do
+      assert_equal '.', subject::PIPE_SIGNAL
+    end
+
+  end
+
+  class TimeoutSetupTests < UnitTests
+    setup do
+      @mutex      = Mutex.new
+      @cond_var   = ConditionVariable.new
+      @seconds    = 0.01
+      @exception  = Class.new(RuntimeError)
+      @return_val = Factory.string
+    end
+    teardown do
+      @cond_var.broadcast
+    end
+
+  end
+
+  class TimeoutTests < TimeoutSetupTests
+    desc "`timeout` method"
+
+    should "interrupt and raise if the block takes too long to run" do
+      assert_raises(TimeoutError) do
+        subject.timeout(@seconds) do
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+        end
+      end
+    end
+
+    should "interrupt and raise if a custom exception is given and block times out" do
+      assert_raises(@exception) do
+        subject.timeout(@seconds, @exception) do
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+        end
+      end
+    end
+
+    should "not interrupt and return the block's return value if there is no timeout" do
+      val = nil
+      assert_nothing_raised do
+        val = subject.timeout(@seconds){ @return_val }
+      end
+      assert_equal @return_val, val
+    end
+
+    should "raise any exception that the block raises" do
+      assert_raises(@exception) do
+        subject.timeout(@seconds){ raise @exception }
+      end
+    end
+
+    should "complain if given a nil seconds value" do
+      assert_raises(ArgumentError) do
+        subject.timeout(nil){ }
+      end
+    end
+
+    should "complain if given a non-numeric seconds value" do
+      assert_raises(ArgumentError) do
+        subject.timeout(Factory.string){ }
+      end
+    end
+
+  end
+
+  class OptionalTimeoutTests < TimeoutSetupTests
+    desc "`optional_timeout` method"
+
+    should "call `timeout` with any given args if seconds is not nil" do
+      # this repeats the relevent tests from the TimeoutTests above
+
+      assert_raises(TimeoutError) do
+        subject.optional_timeout(@seconds) do
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+        end
+      end
+
+      assert_raises(@exception) do
+        subject.optional_timeout(@seconds, @exception) do
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+        end
+      end
+
+      val = nil
+      assert_nothing_raised do
+        val = subject.optional_timeout(@seconds){ @return_val }
+      end
+      assert_equal @return_val, val
+
+      assert_raises(@exception) do
+        subject.optional_timeout(@seconds){ raise @exception }
+      end
+
+      assert_raises(ArgumentError) do
+        subject.optional_timeout(Factory.string){ }
+      end
+    end
+
+    should "call the given block directly if seconds is nil" do
+      val = nil
+      assert_nothing_raised do
+        val = subject.optional_timeout(nil){ sleep @seconds; @return_val }
+      end
+      assert_equal @return_val, val
+
+      assert_raises(@exception) do
+        subject.optional_timeout(nil){ raise @exception }
+      end
+    end
+
+  end
+
+  class JustTimeoutTests < TimeoutSetupTests
+    desc "`just_timeout` method"
+    setup do
+      @val_set = nil
+    end
+
+    should "call `timeout` with the given seconds and :do arg" do
+      # this repeats the relevent tests from the TimeoutTests above
+
+      assert_nothing_raised do
+        subject.just_timeout(@seconds, :do => proc{
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+          @val_set = Factory.string
+        })
+      end
+      assert_nil @val_set
+
+      val = nil
+      assert_nothing_raised do
+        val = subject.just_timeout(@seconds, :do => proc{ @return_val })
+      end
+      assert_equal @return_val, val
+
+      assert_raises(@exception) do
+        subject.just_timeout(@seconds, :do => proc{ raise @exception })
+      end
+
+      assert_raises(ArgumentError) do
+        subject.just_timeout(nil, :do => proc{ })
+      end
+
+      assert_raises(ArgumentError) do
+        subject.just_timeout(Factory.string, :do => proc{ })
+      end
+    end
+
+    should "call any given :on_timeout arg if a timeout occurs" do
+      exp = Factory.string
+      assert_nothing_raised do
+        subject.just_timeout(@seconds, {
+          :do => proc{
+            @mutex.synchronize{ @cond_var.wait(@mutex) }
+          },
+          :on_timeout => proc{ @val_set = exp }
+        })
+      end
+      assert_equal exp, @val_set
+
+      @val_set = val = nil
+      assert_nothing_raised do
+        val = subject.just_timeout(@seconds, {
+          :do         => proc{ @return_val },
+          :on_timeout => proc{ @val_set = exp }
+        })
+      end
+      assert_equal @return_val, val
+      assert_nil @val_set
+    end
+
+    should "complain if not given a :do arg" do
+      assert_raises(ArgumentError) do
+        subject.just_timeout(@seconds){ }
+      end
+      assert_raises(ArgumentError) do
+        subject.just_timeout(@seconds, :do => nil)
+      end
+    end
+
+    should "complain if given a non-proc :do arg" do
+      assert_raises(ArgumentError) do
+        subject.just_timeout(@seconds, :do => Factory.string)
+      end
+    end
+
+    should "complain if given a non-proc :on_timeout arg" do
+      assert_raises(ArgumentError) do
+        subject.just_timeout(@seconds, {
+          :do         => proc{ },
+          :on_timeout => Factory.string
+        })
+      end
+    end
+
+  end
+
+  class JustOptionalTimeoutTests < TimeoutSetupTests
+    desc "`just_optional_timeout` method"
+    setup do
+      @val_set = nil
+    end
+
+    should "call `optional_timeout` with the given seconds and :do arg" do
+      # this repeats the relevent tests from the JustTimeoutTests above
+
+      assert_nothing_raised do
+        subject.just_optional_timeout(@seconds, :do => proc{
+          @mutex.synchronize{ @cond_var.wait(@mutex) }
+          @val_set = Factory.string
+        })
+      end
+      assert_nil @val_set
+
+      val = nil
+      assert_nothing_raised do
+        val = subject.just_optional_timeout(@seconds, :do => proc{ @return_val })
+      end
+      assert_equal @return_val, val
+
+      assert_raises(@exception) do
+        subject.just_optional_timeout(@seconds, :do => proc{ raise @exception })
+      end
+
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout(Factory.string, :do => proc{ })
+      end
+
+      exp = Factory.string
+      assert_nothing_raised do
+        subject.just_optional_timeout(@seconds, {
+          :do => proc{
+            @mutex.synchronize{ @cond_var.wait(@mutex) }
+          },
+          :on_timeout => proc{ @val_set = exp }
+        })
+      end
+      assert_equal exp, @val_set
+
+      @val_set = val = nil
+      assert_nothing_raised do
+        val = subject.just_optional_timeout(@seconds, {
+          :do         => proc{ @return_val },
+          :on_timeout => proc{ @val_set = exp }
+        })
+      end
+      assert_equal @return_val, val
+      assert_nil @val_set
+
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout(@seconds){ }
+      end
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout(@seconds, :do => nil)
+      end
+
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout(@seconds, :do => Factory.string)
+      end
+
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout(@seconds, {
+          :do         => proc{ },
+          :on_timeout => Factory.string
+        })
+      end
+    end
+
+    should "call the given :do arg directly if seconds is nil" do
+      val = nil
+      assert_nothing_raised do
+        val = subject.just_optional_timeout(nil, :do => proc{
+          sleep @seconds
+          @return_val
+        })
+      end
+      assert_equal @return_val, val
+
+      assert_raises(@exception) do
+        subject.just_optional_timeout(nil, :do => proc{ raise @exception })
+      end
+    end
+
+    should "complain if not given a :do arg" do
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout([@seconds, nil].sample){ }
+      end
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout([@seconds, nil].sample, :do => nil)
+      end
+    end
+
+    should "complain if given a non-proc :do arg" do
+      assert_raises(ArgumentError) do
+        subject.just_optional_timeout([@seconds, nil].sample, :do => Factory.string)
+      end
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: much-timeout
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Kelly Redding
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2016-06-06 00:00:00 Z
+date: 2016-06-07 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: assert
@@ -22,7 +22,7 @@ dependencies:
         version: 2.16.1
   type: :development
   version_requirements: *id001
-description: IO.select based timeouts
+description: IO.select based timeouts; an alternative to Ruby's stdlib Timeout module.
 email: 
 - kelly@kellyredding.com
 - collin.redding@me.com
@@ -43,6 +43,7 @@ files:
 - much-timeout.gemspec
 - test/helper.rb
 - test/support/factory.rb
+- test/unit/much-timeout_tests.rb
 - tmp/.gitkeep
 homepage: http://github.com/redding/much-timeout
 licenses: 
@@ -69,7 +70,8 @@ rubyforge_project:
 rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
-summary: IO.select based timeouts
+summary: IO.select based timeouts; an alternative to Ruby's stdlib Timeout module.
 test_files: 
 - test/helper.rb
 - test/support/factory.rb
+- test/unit/much-timeout_tests.rb