stud 0.0.10 → 0.0.11

data/lib/stud/benchmark.rb

@@ -10,20 +10,26 @@ module Stud
   module Benchmark
     def self.run(iterations=1, &block)
       timer = Metriks::Timer.new
+      start = Time.now
       iterations.times { timer.time(&block) }
-      return Results.new(timer)
+      duration = Time.now - start
+      return Results.new(timer, duration)
     end # def run
 
     def self.runtimed(seconds=10, &block)
       timer = Metriks::Timer.new
       expiration = Time.now + seconds
+
+      start = Time.now
       timer.time(&block) while Time.now < expiration
-      return Results.new(timer)
+      duration = Time.now - start
+      return Results.new(timer, duration)
     end # def runtimed
 
     def self.cputimed(seconds=10, &block)
       timer = Metriks::Timer.new
       expiration = Time.now + seconds
+      start_usage = Stud::Benchmark::RUsage.get
       while Time.now < expiration
         start = Stud::Benchmark::RUsage.get
         block.call
@@ -31,7 +37,10 @@ module Stud
         cputime = (finish.user + finish.system) - (start.user + start.system)
         timer.update(cputime)
       end # while not expired
-      return Results.new(timer)
+      finish_usage = Stud::Benchmark::RUsage.get
+      duration = (finish_usage.user + finish_usage.system) \
+        - (start_usage.user + start_usage.system)
+      return Results.new(timer, duration)
     end # self.cpu
 
     class Results
@@ -53,8 +62,9 @@ module Stud
         #tick
       #end.flatten
 
-      def initialize(data)
+      def initialize(data, duration)
         @data = data
+        @duration = duration
       end # def initialize
 
       def environment
@@ -79,6 +89,10 @@ module Stud
         return @data.max
       end
 
+      def rate
+        return @data.count / @duration
+      end
+
       def mean
         return @data.mean
       end # def mean

data/lib/stud/buffer.rb

@@ -0,0 +1,260 @@
+module Stud
+
+  # @author {Alex Dean}[http://github.com/alexdean]
+  #
+  # Implements a generic framework for accepting events which are later flushed
+  # in batches. Flushing occurrs whenever +:max_items+ or +:max_interval+ (seconds)
+  # has been reached.
+  #
+  # Including class must implement +flush+, which will be called with all accumulated
+  # items either when the output buffer fills (+:max_items+) or when a fixed amount
+  # of time (+:max_interval+) passes.
+  #
+  # == batch_receive and flush
+  # General receive/flush can be implemented in one of two ways.
+  #
+  # === batch_receive(event) / flush(events)
+  # +flush+ will receive an array of events which were passed to +buffer_receive+.
+  #
+  #   batch_receive('one')
+  #   batch_receive('two')
+  #
+  # will cause a flush invocation like
+  #
+  #   flush(['one', 'two'])
+  #
+  # === batch_receive(event, group) / flush(events, group)
+  # flush() will receive an array of events, plus a grouping key.
+  #
+  #   batch_receive('one',   :server => 'a')
+  #   batch_receive('two',   :server => 'b')
+  #   batch_receive('three', :server => 'a')
+  #   batch_receive('four',  :server => 'b')
+  #
+  # will result in the following flush calls
+  #
+  #   flush(['one', 'three'], {:server => 'a'})
+  #   flush(['two', 'four'],  {:server => 'b'})
+  #
+  # Grouping keys can be anything which are valid Hash keys. (They don't have to
+  # be hashes themselves.) Strings or Fixnums work fine. Use anything which you'd
+  # like to receive in your +flush+ method to help enable different handling for
+  # various groups of events.
+  #
+  # == on_flush_error
+  # Including class may implement +on_flush_error+, which will be called with an
+  # Exception instance whenever buffer_flush encounters an error.
+  #
+  # * +buffer_flush+ will automatically re-try failed flushes, so +on_flush_error+
+  #   should not try to implement retry behavior.
+  # * Exceptions occurring within +on_flush_error+ are not handled by
+  #   +buffer_flush+.
+  #
+  # == on_full_buffer_receive
+  # Including class may implement +on_full_buffer_receive+, which will be called
+  # whenever +buffer_receive+ is called while the buffer is full.
+  #
+  # +on_full_buffer_receive+ will receive a Hash like <code>{:pending => 30,
+  # :outgoing => 20}</code> which describes the internal state of the module at
+  # the moment.
+  #
+  # == final flush
+  # Including class should call <code>buffer_flush(:final => true)</code> during a teardown/
+  # shutdown routine (after the last call to buffer_receive) to ensure that all
+  # accumulated messages are flushed.
+  module Buffer
+
+    public
+    # Initialize the buffer.
+    #
+    # Call directly from your constructor if you wish to set some non-default
+    # options. Otherwise buffer_initialize will be called automatically during the
+    # first buffer_receive call.
+    #
+    # Options:
+    # * :max_items, Max number of items to buffer before flushing. Default 50.
+    # * :max_interval, Max number of seconds to wait between flushes. Default 5.
+    # * :logger, A logger to write log messages to. No default. Optional.
+    #
+    # @param [Hash] options
+    def buffer_initialize(options={})
+      if ! self.class.method_defined?(:flush)
+        raise ArgumentError, "Any class including Stud::Buffer must define a flush() method."
+      end
+
+      @buffer_config = {
+        :max_items => options[:max_items] || 50,
+        :max_interval => options[:max_interval] || 5,
+        :logger => options[:logger] || nil,
+        :has_on_flush_error => self.class.method_defined?(:on_flush_error),
+        :has_on_full_buffer_receive => self.class.method_defined?(:on_full_buffer_receive)
+      }
+      @buffer_state = {
+        # items accepted from including class
+        :pending_items => {},
+        :pending_count => 0,
+
+        # guard access to pending_items & pending_count
+        :pending_mutex => Mutex.new,
+
+        # items which are currently being flushed
+        :outgoing_items => {},
+        :outgoing_count => 0,
+
+        # ensure only 1 flush is operating at once
+        :flush_mutex => Mutex.new,
+
+        # data for timed flushes
+        :last_flush => Time.now.to_i,
+        :timer => Thread.new do
+          loop do
+            sleep(@buffer_config[:max_interval])
+            buffer_flush(:force => true)
+          end
+        end
+      }
+
+      # events we've accumulated
+      buffer_clear_pending
+    end
+
+    # Determine if +:max_items+ has been reached.
+    #
+    # buffer_receive calls will block while <code>buffer_full? == true</code>.
+    #
+    # @return [bool] Is the buffer full?
+    def buffer_full?
+      @buffer_state[:pending_count] + @buffer_state[:outgoing_count] >= @buffer_config[:max_items]
+    end
+
+    # Save an event for later delivery
+    #
+    # Events are grouped by the (optional) group parameter you provide.
+    # Groups of events, plus the group name, are later passed to +flush+.
+    #
+    # This call will block if +:max_items+ has been reached.
+    #
+    # @see Stud::Buffer The overview has more information on grouping and flushing.
+    #
+    # @param event An item to buffer for flushing later.
+    # @param group Optional grouping key. All events with the same key will be
+    #              passed to +flush+ together, along with the grouping key itself.
+    def buffer_receive(event, group=nil)
+      buffer_initialize if ! @buffer_state
+
+      # block if we've accumulated too many events
+      while buffer_full? do
+        on_full_buffer_receive(
+          :pending => @buffer_state[:pending_count],
+          :outgoing => @buffer_state[:outgoing_count]
+        ) if @buffer_config[:has_on_full_buffer_receive]
+        sleep 0.1
+      end
+
+      @buffer_state[:pending_mutex].synchronize do
+        @buffer_state[:pending_items][group] << event
+        @buffer_state[:pending_count] += 1
+      end
+
+      buffer_flush
+    end
+
+    # Try to flush events.
+    #
+    # Returns immediately if flushing is not necessary/possible at the moment:
+    # * :max_items have not been accumulated
+    # * :max_interval seconds have not elapased since the last flush
+    # * another flush is in progress
+    #
+    # <code>buffer_flush(:force => true)</code> will cause a flush to occur even
+    # if +:max_items+ or +:max_interval+ have not been reached. A forced flush
+    # will still return immediately (without flushing) if another flush is
+    # currently in progress.
+    #
+    # <code>buffer_flush(:final => true)</code> is identical to <code>buffer_flush(:force => true)</code>,
+    # except that if another flush is already in progress, <code>buffer_flush(:final => true)</code>
+    # will block/wait for the other flush to finish before proceeding.
+    #
+    # @param [Hash] options Optional. May be <code>{:force => true}</code> or <code>{:final => true}</code>.
+    # @return [Fixnum] The number of items successfully passed to +flush+.
+    def buffer_flush(options={})
+      force = options[:force] || options[:final]
+      final = options[:final]
+
+      # final flush will wait for lock, so we are sure to flush out all buffered events
+      if options[:final]
+        @buffer_state[:flush_mutex].lock
+      elsif ! @buffer_state[:flush_mutex].try_lock # failed to get lock, another flush already in progress
+        return 0
+      end
+
+      items_flushed = 0
+
+      begin
+        time_since_last_flush = Time.now.to_i - @buffer_state[:last_flush]
+
+        return 0 if @buffer_state[:pending_count] == 0
+        return 0 if (!force) &&
+           (@buffer_state[:pending_count] < @buffer_config[:max_items]) &&
+           (time_since_last_flush < @buffer_config[:max_interval])
+
+        @buffer_state[:pending_mutex].synchronize do
+          @buffer_state[:outgoing_items] = @buffer_state[:pending_items]
+          @buffer_state[:outgoing_count] = @buffer_state[:pending_count]
+          buffer_clear_pending
+        end
+
+        @buffer_config[:logger].debug("Flushing output",
+          :outgoing_count => @buffer_state[:outgoing_count],
+          :time_since_last_flush => time_since_last_flush,
+          :outgoing_events => @buffer_state[:outgoing_items],
+          :batch_timeout => @buffer_config[:max_interval],
+          :force => force,
+          :final => final
+        ) if @buffer_config[:logger]
+
+        @buffer_state[:outgoing_items].each do |group, events|
+          begin
+            if group.nil?
+              flush(events)
+            else
+              flush(events, group)
+            end
+
+            @buffer_state[:outgoing_items].delete(group)
+            events_size = events.size
+            @buffer_state[:outgoing_count] -= events_size
+            items_flushed += events_size
+
+          rescue => e
+
+            @buffer_config[:logger].warn("Failed to flush outgoing items",
+              :outgoing_count => @buffer_state[:outgoing_count],
+              :exception => e,
+              :backtrace => e.backtrace
+            ) if @buffer_config[:logger]
+
+            if @buffer_config[:has_on_flush_error]
+              on_flush_error e
+            end
+
+            sleep 1
+            retry
+          end
+          @buffer_state[:last_flush] = Time.now.to_i
+        end
+
+      ensure
+        @buffer_state[:flush_mutex].unlock
+      end
+
+      items_flushed
+    end
+
+    private
+    def buffer_clear_pending
+      @buffer_state[:pending_items] = Hash.new { |h, k| h[k] = [] }
+      @buffer_state[:pending_count] = 0
+    end
+  end
+end

data/lib/stud/trap.rb

@@ -1,4 +1,23 @@
 module Stud
+  # Bind a block to be called when a certain signal is received.
+  #
+  # Same arguments to Signal::trap.
+  #
+  # The behavior of this method is different than Signal::trap because
+  # multiple handlers can request notification for the same signal.
+  #
+  # For example, this is valid:
+  #
+  #     Stud.trap("INT") { puts "Hello" }
+  #     Stud.trap("INT") { puts "World" }
+  #
+  # When SIGINT is received, both callbacks will be invoked, in order.
+  #
+  # This helps avoid the situation where a library traps a signal outside of
+  # your control.
+  #
+  # If something has already used Signal::trap, that callback will be saved
+  # and scheduled the same way as any other Stud::trap.
   def self.trap(signal, &block)
     @traps ||= Hash.new { |h,k| h[k] = [] }
 
@@ -16,13 +35,25 @@ module Stud
     end
 
     @traps[signal] << block
-  end
 
+    return block.id
+  end # def self.trap
+
+  # Simulate a signal. This lets you force an interrupt without
+  # sending a signal to yourself.
   def self.simulate_signal(signal)
-    puts "Simulate: #{signal} w/ #{@traps[signal].count} callbacks"
+    #puts "Simulate: #{signal} w/ #{@traps[signal].count} callbacks"
     @traps[signal].each(&:call)
-  end
-end
+  end # def self.simulate_signal
+
+  # Remove a previously set signal trap.
+  #
+  # 'signal' is the name of the signal ("INT", etc)
+  # 'id' is the value returned by a previous Stud.trap() call
+  def self.untrap(signal, id)
+    @traps[signal].delete_if { |block| block.id == id }
+  end # def self.untrap
+end # module Studd
 
 # Monkey-patch the main 'trap' stuff? This could be useful.
 #module Signal

metadata

@@ -1,130 +1,123 @@
 --- !ruby/object:Gem::Specification
 name: stud
 version: !ruby/object:Gem::Version
-  version: 0.0.10
-  prerelease:
+  version: 0.0.11
+  prerelease: 
 platform: ruby
 authors:
 - Jordan Sissel
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-15 00:00:00.000000000 Z
+date: 2013-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: metriks
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
-    none: false
-  prerelease: false
-  type: :runtime
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ffi
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
-    none: false
-  prerelease: false
-  type: :runtime
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
-    none: false
-  prerelease: false
-  type: :development
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: insist
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: !binary |-
-          MA==
-    none: false
-  prerelease: false
-  type: :development
-description: small reusable bits of code I'm tired of writing over and over. A library form of my software-patterns github repo.
+        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
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/stud/task.rb
-- lib/stud/benchmark.rb
+- lib/stud/benchmark/rusage.rb
+- lib/stud/interval.rb
 - lib/stud/pool.rb
+- lib/stud/secret.rb
 - lib/stud/try.rb
-- lib/stud/interval.rb
+- lib/stud/task.rb
+- lib/stud/buffer.rb
+- lib/stud/benchmark.rb
 - lib/stud/trap.rb
-- lib/stud/secret.rb
-- lib/stud/benchmark/rusage.rb
 - LICENSE
 - CHANGELIST
 - README.md
 homepage: https://github.com/jordansissel/ruby-stud
 licenses: []
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: !binary |-
-        MA==
-  none: false
+      version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: !binary |-
-        MA==
-  none: false
+      version: '0'
 requirements: []
-rubyforge_project:
+rubyforge_project: 
 rubygems_version: 1.8.24
-signing_key:
+signing_key: 
 specification_version: 3
 summary: stud - common code techniques
 test_files: []
+has_rdoc: