stud 0.0.1 → 0.0.2

data/README.md

@@ -0,0 +1,27 @@
+# Stud.
+
+Ruby's stdlib is missing many things I use to solve most of my software
+problems. Things like like retrying on a failure, supervising workers, resource
+pools, etc.
+
+In general, I started exploring solutions to these things in code over in my
+[software-patterns](https://github.com/jordansissel/software-patterns) repo.
+This library (stud) aims to be a well-tested, production-quality implementation
+of the patterns described in that repo.
+
+For now, these all exist in a single repo because, so far, implementations of
+each 'pattern' are quite small by code size.
+
+## Features
+
+* retry on failure, with back-off, where failure is any exception.
+* generic resource pools
+* supervising tasks
+* tasks (threads that can return values, exceptions, etc)
+* interval execution (do X every N seconds)
+
+## TODO:
+
+* Make sure all things are documented. rubydoc.info should be able to clearly
+  show folks how to use features of this library.
+* Add tests to cover all supported features.

data/lib/stud/try.rb

@@ -1,75 +1,119 @@
 module Stud
-  # Public: try a block of code until either it succeeds or we give up.
-  #
-  # enumerable - an Enumerable or omitted, #each is invoked and is tried that
-  #   number of times. If this value is omitted or nil, we will try until
-  #   success with no limit on the number of tries.
-  #
-  # Returns the return value of the block once the block succeeds.
-  # Raises the last seen exception if we run out of tries.
+
+  # A class implementing 'retry-on-failure'
   #
-  # Examples
+  # Example:
   #
-  #   # Try 10 times to fetch http://google.com/
-  #   response = try(10.times) { Net::HTTP.get_response("google.com", "/") }
+  #     Try.new.try(5.times) { your_code }
   #
-  #   # Try many times, yielding the value of the enumeration to the block.
-  #   # This allows you to try different inputs.
-  #   response = try([0, 2, 4, 6]) { |val| 50 / val }
-  #   
-  #   Output: 
-  #   Failed (divided by 0). Retrying in 0.01 seconds...
-  #   => 25
+  # A failure is indicated by any exception being raised.
+  # On success, the return value of the block is the return value of the try
+  # call.
   #
-  #   # Try forever
-  #   return_value = try { ... }
-  def try(enumerable=nil, &block)
-    if block.arity == 0
-      # If the block takes no arguments, give none
-      procedure = lambda { |val| block.call }
-    else
-      # Otherwise, pass the current 'enumerable' value to the block.
-      procedure = lambda { |val| block.call(val) }
-    end
+  # On final failure (ran out of things to try), the last exception is raised.
+  class Try
+    # An infinite enumerator
+    class Forever
+      include Enumerable
+      def each(&block)
+        a = 0
+        yield a += 1 while true
+      end
+    end # class Forever
 
-    last_exception = nil
+    FOREVER = Forever.new
 
-    # Retry after a sleep to be nice.
-    backoff = 0.01
-    backoff_max = 2.0
+    BACKOFF_SCHEDULE = [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.0]
 
-    # Try forever if enumerable is nil.
-    if enumerable.nil?
-      enumerable = Enumerator.new do |y| 
-        a = 0
-        while true
-          a += 1
-          y << a
-        end
-      end
-    end
+    # Log a failure.
+    #
+    # You should override this method if you want a better logger.
+    def log_failure(exception, fail_count, message)
+      puts "Failed (#{exception}). #{message}"
+    end # def log_failure
 
-    # When 'enumerable' runs out of things, if we still haven't succeeded, we'll
-    # reraise
-    enumerable.each do |val|
-      begin
-        # If the 'procedure' (the block, really) succeeds, we'll break 
-        # and return the return value of the block. Win!
-        return procedure.call(val)
-      rescue => e
-        puts "Failed (#{e}). Retrying in #{backoff} seconds..."
-        last_exception = e
+    # This method is called when a try attempt fails.
+    #
+    # The default implementation will sleep with exponential backoff up to a
+    # maximum of 2 seconds (see BACKOFF_SCHEDULE)
+    #
+    # exception - the exception causing the failure
+    # fail_count - how many times we have failed.
+    def failure(exception, fail_count)
+      backoff = BACKOFF_SCHEDULE[fail_count] || BACKOFF_SCHEDULE.last
+      log_failure(exception, fail_count, "Sleeping for #{backoff}")
+      sleep(backoff)
+    end # def failure
 
-        # Exponential backoff
-        sleep(backoff)
-        backoff = [backoff * 2, backoff_max].min unless backoff == backoff_max
+    # Public: try a block of code until either it succeeds or we give up.
+    #
+    # enumerable - an Enumerable or omitted/nil, #each is invoked and is tried
+    #   that number of times. If this value is omitted or nil, we will try until
+    #   success with no limit on the number of tries.
+    #
+    # Returns the return value of the block once the block succeeds.
+    # Raises the last seen exception if we run out of tries.
+    #
+    # Examples
+    #
+    #   # Try 10 times to fetch http://google.com/
+    #   response = try(10.times) { Net::HTTP.get_response("google.com", "/") }
+    #
+    #   # Try many times, yielding the value of the enumeration to the block.
+    #   # This allows you to try different inputs.
+    #   response = try([0, 2, 4, 6]) { |val| 50 / val }
+    #   
+    #   Output: 
+    #   Failed (divided by 0). Retrying in 0.01 seconds...
+    #   => 25
+    #
+    #   # Try forever
+    #   return_value = try { ... }
+    def try(enumerable=FOREVER, &block)
+      if block.arity == 0
+        # If the block takes no arguments, give none
+        procedure = lambda { |val| block.call }
+      else
+        # Otherwise, pass the current 'enumerable' value to the block.
+        procedure = lambda { |val| block.call(val) }
       end
-    end
 
-    # generally make the exception appear from the 'try' method itself, not from
-    # any deeply nested enumeration/begin/etc
-    last_exception.set_backtrace(StandardError.new.backtrace)
-    raise last_exception
+      # Track the last exception so we can reraise it on failure.
+      last_exception = nil
+
+      # When 'enumerable' runs out of things, if we still haven't succeeded,
+      # we'll reraise
+      fail_count = 0
+      enumerable.each do |val|
+        begin
+          # If the 'procedure' (the block, really) succeeds, we'll break 
+          # and return the return value of the block. Win!
+          return procedure.call(val)
+        rescue => exception
+          last_exception = exception
+          fail_count += 1
+
+          # Note: Since we can't reliably detect the 'end' of an enumeration, we
+          # will call 'failure' for the final iteration (if it failed) and sleep
+          # even though there's no strong reason to backoff on the last error.
+          failure(exception, fail_count)
+        end
+      end # enumerable.each
+
+      # generally make the exception appear from the 'try' method itself, not from
+      # any deeply nested enumeration/begin/etc
+      # It is my hope that this makes the backtraces easier to read, not more
+      # difficult. If you find this is not the case, please please please let me
+      # know.
+      last_exception.set_backtrace(StandardError.new.backtrace)
+      raise last_exception
+    end # def try
+  end # class Stud::Try
+
+  TRY = Try.new
+  # A simple try method for the common case.
+  def try(enumerable=Stud::Try::Forever, &block)
+    return TRY.try(enumerable, &block)
   end # def try
 
   extend self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stud
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,39 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2012-06-10 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: insist
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: small reusable bits of code I'm tired of writing over and over. A library
   form of my software-patterns github repo.
 email: jls@semicomplete.com