progress-reporters 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 66a446c2c9ee4116e599389eef90ab5f608c4cf1
+  data.tar.gz: 9a7249c0fff340985ad787cbbcec102235b3035b
+SHA512:
+  metadata.gz: 5a83ed6314162a9005a517ad286d2d5101ddddaa5da23010beabdebef1567eb55b902d8edc4c65c7961395c41fe6ae249f0ec082a7cffd7862d7773fca383741
+  data.tar.gz: 1d8ac329f8646b2e94f08000d7bb831088f8acf93b0f789ba5fa14d25542c216d352fe3eb30bd9bbca893fc50810b102399a2e8e5ee7ff59596f4916b10d2da8

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem 'pry-nav'
+  gem 'rake'
+  gem 'timecop', '~> 0.7.0'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'rr'
+end

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0
+
+* Birthday!

data/Rakefile

@@ -0,0 +1,18 @@
+# encoding: UTF-8
+
+require 'rubygems' unless ENV['NO_RUBYGEMS']
+
+require 'bundler'
+require 'rspec/core/rake_task'
+require 'rubygems/package_task'
+
+require './lib/progress-reporters'
+
+Bundler::GemHelper.install_tasks
+
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = './spec/**/*_spec.rb'
+end

data/lib/progress-reporters.rb

@@ -0,0 +1,9 @@
+# encoding: UTF-8
+
+module ProgressReporters
+  autoload :ProgressReporter,          'progress-reporters/progress_reporter'
+  autoload :NilProgressReporter,       'progress-reporters/nil_progress_reporter'
+  autoload :StagedProgressReporter,    'progress-reporters/staged_progress_reporter'
+  autoload :NilStagedProgressReporter, 'progress-reporters/nil_staged_progress_reporter'
+  autoload :MeteredProgressReporter,   'progress-reporters/metered_progress_reporter'
+end

data/lib/progress-reporters/metered_progress_reporter.rb

@@ -0,0 +1,117 @@
+# encoding: UTF-8
+
+module ProgressReporters
+
+  class MeteredProgressReporter < ProgressReporter
+    CALC_TYPES = [:avg, :moving_avg]
+    DEFAULT_MOVING_AVG_WINDOW_SIZE = 5
+    DEFAULT_CALC_TYPE = :moving_avg
+    DEFAULT_PRECISION = 2
+
+    attr_reader :calc_type, :window_size, :precision
+
+    def set_calc_type(calc_type)
+      if CALC_TYPES.include?(calc_type)
+        @calc_type = calc_type
+        self
+      else
+        raise ArgumentError, "#{calc_type} is not a supported calculation type."
+      end
+    end
+
+    def set_window_size(window_size)
+      @window_size = window_size
+      self
+    end
+
+    def set_precision(precision)
+      @precision = precision
+      self
+    end
+
+    def reset
+      super
+      @avg_sum = 0
+      @avg_count = 0
+      @avg_time_sum = 0
+      @avg_window = []
+      @avg_time_window = []
+      @last_timestamp = nil
+      @last_count = nil
+    end
+
+    def window_size
+      (@window_size || DEFAULT_MOVING_AVG_WINDOW_SIZE).to_f
+    end
+
+    def calc_type
+      @calc_type || DEFAULT_CALC_TYPE
+    end
+
+    def precision
+      @precision || DEFAULT_PRECISION
+    end
+
+    protected
+
+    # this won't get called if on_progress_proc is nil
+    def notify_of_progress(count, total)
+      on_progress_proc.call(
+        count, total, percentage(count, total), rate(count, total)
+      )
+    end
+
+    def rate(count, total)
+      cur_time = Time.now
+
+      rate = if @last_timestamp
+        time_delta = cur_time - @last_timestamp
+        count_delta = count - last_count
+        apply_calc_type(time_delta, count_delta)
+      else
+        0
+      end
+
+      @last_timestamp = cur_time
+      @last_count = count
+      rate
+    end
+
+    def apply_calc_type(time_delta, count_delta)
+      case calc_type
+        when :avg
+          apply_avg(time_delta, count_delta)
+        when :moving_avg
+          apply_moving_avg(time_delta, count_delta)
+      end
+    end
+
+    def apply_avg(time_delta, count_delta)
+      @avg_sum += count_delta
+      @avg_time_sum += time_delta
+      @avg_count += 1
+
+      # (avg items) / (avg time) = avg items per second
+      answer = (@avg_sum / @avg_count) / (@avg_time_sum / @avg_count)
+      answer.round(precision)
+    end
+
+    def apply_moving_avg(time_delta, count_delta)
+      add_window_element(time_delta, count_delta)
+      avg_count = @avg_window.inject(&:+) / window_size
+      avg_time = @avg_time_window.inject(&:+) / window_size
+      (avg_count / avg_time).round(precision)
+    end
+
+    def add_window_element(time_delta, count_delta)
+      if @avg_window.size >= window_size
+        @avg_window.shift
+        @avg_time_window.shift
+      end
+
+      @avg_window << count_delta
+      @avg_time_window << time_delta
+    end
+  end
+
+end

data/lib/progress-reporters/nil_progress_reporter.rb

@@ -0,0 +1,27 @@
+# encoding: UTF-8
+
+module ProgressReporters
+
+  class NilProgressReporter
+    def self.instance
+      @instance ||= new
+    end
+
+    def on_progress(&block)
+      self
+    end
+
+    def on_complete(&block)
+      self
+    end
+
+    def set_step(step)
+      self
+    end
+
+    def report_progress(count, total); end
+    def report_complete; end
+    def reset; end
+  end
+
+end

data/lib/progress-reporters/nil_staged_progress_reporter.rb

@@ -0,0 +1,21 @@
+# encoding: UTF-8
+
+module ProgressReporters
+
+  class NilStagedProgressReporter < NilProgressReporter
+    def on_stage_changed(&block)
+      self
+    end
+
+    def on_stage_finished(&block)
+    end
+
+    def set_stage(stage)
+      self
+    end
+
+    def change_stage(new_stage); end
+    def report_stage_finished(count, total); end
+  end
+
+end

data/lib/progress-reporters/progress_reporter.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+
+module ProgressReporters
+
+  class ProgressReporter
+    DEFAULT_STEP = 1
+
+    attr_reader :step, :last_count, :on_progress_proc, :on_complete_proc
+
+    protected :on_progress_proc
+    protected :on_complete_proc
+
+    def initialize
+      @step = DEFAULT_STEP
+      reset
+    end
+
+    def on_progress(&block)
+      @on_progress_proc = block
+      self
+    end
+
+    def on_complete(&block)
+      @on_complete_proc = block
+      self
+    end
+
+    def set_step(step)
+      @step = step
+      self
+    end
+
+    def report_progress(count, total)
+      if on_progress_proc
+        notify_of_progress(count, total) if count % step == 0
+      end
+
+      @last_count = count
+    end
+
+    def report_complete
+      if on_complete_proc
+        notify_of_completion
+      end
+    end
+
+    def reset
+      @last_count = 0
+    end
+
+    protected
+
+    # this won't get called if on_progress_proc is nil
+    def notify_of_progress(count, total)
+      on_progress_proc.call(
+        count, total, percentage(count, total)
+      )
+    end
+
+    # this won't get called if on_complete_proc is nil
+    def notify_of_completion
+      on_complete_proc.call
+    end
+
+    private
+
+    def percentage(count, total, precision = 0)
+      if total > 0
+        ((count.to_f / total.to_f) * 100).round(precision)
+      else
+        0
+      end
+    end
+  end
+
+end

data/lib/progress-reporters/staged_progress_reporter.rb

@@ -0,0 +1,70 @@
+# encoding: UTF-8
+
+module ProgressReporters
+
+  class StagedProgressReporter < ProgressReporter
+    DEFAULT_STAGE = :start
+
+    attr_reader :stage, :on_stage_changed_proc, :on_stage_finished_proc
+    protected :on_stage_changed_proc
+    protected :on_stage_finished_proc
+
+    def initialize
+      super
+      @stage = DEFAULT_STAGE
+    end
+
+    def set_stage(stage)
+      @stage = stage
+      self
+    end
+
+    def change_stage(new_stage)
+      if on_stage_changed_proc
+        notify_of_stage_change(new_stage, stage)
+      end
+
+      @stage = new_stage
+    end
+
+    def report_stage_finished(count, total)
+      if on_stage_finished_proc
+        notify_of_stage_finish(count, total)
+      end
+
+      @last_count = count
+    end
+
+    def on_stage_changed(&block)
+      @on_stage_changed_proc = block
+      self
+    end
+
+    def on_stage_finished(&block)
+      @on_stage_finished_proc = block
+      self
+    end
+
+    protected
+
+    # this won't get called if on_progress_proc is nil
+    def notify_of_progress(count, total)
+      on_progress_proc.call(
+        count, total, percentage(count, total), stage
+      )
+    end
+
+    # this won't get called if on_finished_proc is nil
+    def notify_of_stage_finish(count, total)
+      on_stage_finished_proc.call(
+        count, total, percentage(count, total), stage
+      )
+    end
+
+    # this won't get called if on_stage_changed_proc is nil
+    def notify_of_stage_change(new_stage, old_stage)
+      on_stage_changed_proc.call(new_stage, old_stage)
+    end
+  end
+
+end

data/lib/progress-reporters/version.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+
+module ProgressReporters
+  VERSION = '1.0.0'
+end

data/spec/metered_progress_reporter_spec.rb

@@ -0,0 +1,53 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+include ProgressReporters
+
+describe ProgressReporters::MeteredProgressReporter do
+  before(:each) do
+    collector  # call to instantiate collector
+  end
+
+  context 'with a metered reporter' do
+    let(:reporter) { MeteredProgressReporter.new }
+    let(:collector) { MeteredCollector.new(reporter) }
+
+    context 'with a staged task' do
+      let(:task) { MeteredTask.new(reporter) }
+
+      it 'reports progress and calculates the average rate' do
+        reporter.set_calc_type(:avg)
+        task.execute(10, 0.5, 0)
+
+        collector.progress_notifications.each_with_index do |notification, idx|
+          expect(notification.quantity).to eq(idx)
+          expect(notification.total).to eq(10)
+          expect(notification.percentage).to eq(idx * 10)
+          expect(notification.rate).to eq(idx == 0 ? 0 : 2.0)
+        end
+      end
+
+      it 'reports progress and calculates the moving average rate' do
+        reporter.set_calc_type(:moving_avg)
+        reporter.set_window_size(2)
+        task.execute(10, 1, 1)
+
+        collector.progress_notifications.each_with_index do |notification, idx|
+          expect(notification.quantity).to eq(idx)
+          expect(notification.total).to eq(10)
+          expect(notification.percentage).to eq(idx * 10)
+
+          rate = case idx
+            when 0 then 0.0
+            when 1 then 1.0
+            else
+              (1 / (0.5 + (idx - 1))).round(2)
+          end
+
+          expect(notification.rate).to eq(rate)
+        end
+      end
+    end
+  end
+end

data/spec/progress_reporter_spec.rb

@@ -0,0 +1,67 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+include ProgressReporters
+
+describe ProgressReporters::ProgressReporter do
+  before(:each) do
+    collector  # call to instantiate collector
+  end
+
+  context 'with a linear reporter' do
+    let(:reporter) { ProgressReporter.new }
+    let(:collector) { LinearCollector.new(reporter) }
+
+    context 'with a linear task' do
+      let(:task) { LinearTask.new(reporter) }
+
+      it 'reports progress' do
+        task.execute(10)
+
+        collector.progress_notifications.each_with_index do |notification, idx|
+          expect(notification.quantity).to eq(idx)
+          expect(notification.total).to eq(10)
+          expect(notification.percentage).to eq(10 * idx)
+        end
+
+        expect(collector.complete_notification).to_not be_nil
+      end
+
+      it 'should only report progress every other time when step is set to 2' do
+        reporter.set_step(2)
+        task.execute(10)
+
+        expect(collector.progress_notifications.size).to eq(5)
+
+        collector.progress_notifications.each_with_index do |notification, idx|
+          expect(notification.quantity).to eq(idx * 2)
+          expect(notification.total).to eq(10)
+          expect(notification.percentage).to eq(10 * (idx * 2))
+        end
+      end
+
+      it 'should be able to reset itself' do
+        task.execute(10)
+        expect(reporter.last_count).to eq(9)
+        reporter.reset
+        expect(reporter.last_count).to eq(0)
+      end
+    end
+
+    context 'with a nil reporter' do
+      let(:reporter) { NilProgressReporter.new }
+      let(:collector) { LinearCollector.new(reporter) }
+
+      context 'with a linear task' do
+        let(:task) { LinearTask.new(reporter) }
+
+        it 'should not actually report any progress' do
+          task.execute(10)
+          expect(collector.progress_notifications).to be_empty
+          expect(collector.complete_notification).to be_nil
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,127 @@
+# encoding: UTF-8
+
+require 'rspec'
+require 'progress-reporters'
+require 'timecop'
+require 'pry-nav'
+
+RSpec.configure do |config|
+  config.mock_with :rr
+end
+
+LinearNotification = Struct.new(:quantity, :total, :percentage)
+StagedNotification = Struct.new(:quantity, :total, :percentage, :stage)
+StageChangedNotification = Struct.new(:new_stage, :old_stage)
+MeteredNotification = Struct.new(:quantity, :total, :percentage, :rate)
+
+class LinearCollector
+  attr_reader :progress_reporter
+  attr_reader :progress_notifications, :complete_notification
+
+  def initialize(progress_reporter)
+    @progress_notifications = []
+
+    @progress_reporter = progress_reporter
+      .on_progress { |*args| on_progress(*args) }
+      .on_complete { |*args| on_complete(*args) }
+
+    after_initialize
+  end
+
+  protected
+
+  def after_initialize
+  end
+
+  def on_progress(*args)
+    @progress_notifications << make_notification(*args)
+  end
+
+  def on_complete(*args)
+    if @complete_notification
+      raise StandardError, 'task already complete'
+    else
+      @complete_notification = make_notification(*args)
+    end
+  end
+
+  def make_notification(*args)
+    LinearNotification.new(*args)
+  end
+end
+
+class StagedCollector < LinearCollector
+  attr_reader :stage_changed_notifications
+
+  protected
+
+  def after_initialize
+    @stage_changed_notifications = []
+    progress_reporter.on_stage_changed { |*args| on_stage_changed(*args) }
+  end
+
+  def on_stage_changed(*args)
+    @stage_changed_notifications << StageChangedNotification.new(*args)
+  end
+
+  def make_notification(*args)
+    StagedNotification.new(*args)
+  end
+end
+
+class MeteredCollector < LinearCollector
+  def make_notification(*args)
+    MeteredNotification.new(*args)
+  end
+end
+
+class Task
+  attr_reader :progress_reporter
+
+  def initialize(progress_reporter)
+    @progress_reporter = progress_reporter
+  end
+end
+
+class LinearTask < Task
+  def execute(quantity = 10)
+    quantity.times do |i|
+      progress_reporter.report_progress(i, quantity)
+    end
+
+    progress_reporter.report_complete
+  end
+end
+
+class StagedTask < Task
+  def execute(stages = 2, quantity_per_stage = 10)
+    progress_reporter.set_stage(:stage_1)
+
+    stages.times do |stage|
+      quantity_per_stage.times do |i|
+        progress_reporter.report_progress(i, quantity_per_stage)
+      end
+
+      progress_reporter.report_stage_finished(
+        quantity_per_stage, quantity_per_stage
+      )
+
+      progress_reporter.change_stage(:"stage_#{stage + 2}")
+    end
+
+    progress_reporter.report_complete
+  end
+end
+
+class MeteredTask < Task
+  def execute(quantity = 10, delay_seconds = 1, rate_of_delay = 1)
+    Timecop.freeze do
+      quantity.times do |i|
+        progress_reporter.report_progress(i, quantity)
+        Timecop.travel(Time.now + delay_seconds + (rate_of_delay * i))
+      end
+
+      progress_reporter.report_complete
+    end
+  end
+end

data/spec/staged_progress_reporter_spec.rb

@@ -0,0 +1,63 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+include ProgressReporters
+
+describe ProgressReporters::StagedProgressReporter do
+  before(:each) do
+    collector  # call to instantiate collector
+  end
+
+  context 'with a staged reporter' do
+    let(:reporter) { StagedProgressReporter.new }
+    let(:collector) { StagedCollector.new(reporter) }
+
+    context 'with a staged task' do
+      let(:task) { StagedTask.new(reporter) }
+
+      it 'reports progress in stages' do
+        task.execute(2, 10)
+
+        expect(collector.progress_notifications.size).to eq(20)
+
+        collector.progress_notifications.each_with_index do |notification, idx|
+          expect(notification.quantity).to eq(idx % 10)
+          expect(notification.total).to eq(10)
+          expect(notification.percentage).to eq((idx % 10) * 10)
+          expect(notification.stage).to eq(:"stage_#{(idx / 10) + 1}")
+        end
+
+        expect(collector.stage_changed_notifications.size).to eq(2)
+
+        collector.stage_changed_notifications.tap do |notifications|
+          notifications[0].first do |notification|
+            expect(notification.old_stage).to_eq(:stage_1)
+            expect(notification.new_stage).to eq(:stage_2)
+          end
+
+          notifications[1].first do |notification|
+            expect(notification.old_stage).to_eq(:stage_2)
+            expect(notification.new_stage).to eq(:stage_3)
+          end
+        end
+      end
+    end
+
+    context 'with a nil reporter' do
+      let(:reporter) { NilStagedProgressReporter.new }
+      let(:collector) { StagedCollector.new(reporter) }
+
+      context 'with a linear task' do
+        let(:task) { StagedTask.new(reporter) }
+
+        it 'should not actually report any progress' do
+          task.execute(10)
+          expect(collector.progress_notifications).to be_empty
+          expect(collector.stage_changed_notifications).to be_empty
+          expect(collector.complete_notification).to be_nil
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: progress-reporters
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cameron Dutro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-23 00:00:00.000000000 Z
+dependencies: []
+description: Callback-oriented way to report the progress of a task.
+email:
+- camertron@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- History.txt
+- Rakefile
+- lib/progress-reporters.rb
+- lib/progress-reporters/metered_progress_reporter.rb
+- lib/progress-reporters/nil_progress_reporter.rb
+- lib/progress-reporters/nil_staged_progress_reporter.rb
+- lib/progress-reporters/progress_reporter.rb
+- lib/progress-reporters/staged_progress_reporter.rb
+- lib/progress-reporters/version.rb
+- spec/metered_progress_reporter_spec.rb
+- spec/progress_reporter_spec.rb
+- spec/spec_helper.rb
+- spec/staged_progress_reporter_spec.rb
+homepage: http://github.com/camertron
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Callback-oriented way to report the progress of a task.
+test_files: []