benchmark-memory 0.1.2 → 0.2.0

data/lib/benchmark/memory/job/io_output/metric_formatter.rb

@@ -1,4 +1,6 @@
-require "benchmark/memory/helpers"
+# frozen_string_literal: true
+
+require 'benchmark/memory/helpers'
 
 module Benchmark
   module Memory
@@ -22,10 +24,26 @@ module Benchmark
           #
           # @return [String]
           def to_s
-            [
-              format("%s %s", scale(metric.allocated), metric.type),
-              format("(%s retained)", scale(metric.retained)),
-            ].join(" ")
+            [allocated_message, retained_message].join(' ')
+          end
+
+          private
+
+          # @return [String] the formated string for allocated memory
+          def allocated_message
+            format(
+              '%<allocated>s %<type>s',
+              allocated: scale(metric.allocated),
+              type: metric.type
+            )
+          end
+
+          # @return [String] the formated string for retained memory
+          def retained_message
+            format(
+              '(%<retained>s retained)',
+              retained: scale(metric.retained)
+            )
           end
         end
       end

data/lib/benchmark/memory/job/io_output.rb

@@ -1,5 +1,7 @@
-require "benchmark/memory/job/io_output/comparison_formatter"
-require "benchmark/memory/job/io_output/entry_formatter"
+# frozen_string_literal: true
+
+require 'benchmark/memory/job/io_output/comparison_formatter'
+require 'benchmark/memory/job/io_output/entry_formatter'
 
 module Benchmark
   module Memory
@@ -25,7 +27,7 @@ module Benchmark
         # @return [void]
         def put_comparison(comparison)
           @io.puts
-          @io.puts "Comparison:"
+          @io.puts 'Comparison:'
           @io.puts ComparisonFormatter.new(comparison)
         end
 
@@ -33,7 +35,7 @@ module Benchmark
         #
         # @return [void]
         def put_header
-          @io.puts "Calculating -------------------------------------"
+          @io.puts 'Calculating -------------------------------------'
         end
 
         # Put a notice that the execution is holding for another run.
@@ -41,8 +43,8 @@ module Benchmark
         # @return [void]
         def put_hold_notice
           @io.puts
-          @io.puts "Pausing here -- run Ruby again to " \
-                   "measure the next benchmark..."
+          @io.puts 'Pausing here -- run Ruby again to ' \
+                   'measure the next benchmark...'
         end
       end
     end

data/lib/benchmark/memory/job/null_output.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Benchmark
   module Memory
     class Job
@@ -6,20 +8,17 @@ module Benchmark
         # Swallow entry output.
         #
         # @return [void]
-        def put_entry(entry)
-        end
+        def put_entry(entry); end
 
         # Swallow comparison output.
         #
         # @return [void]
-        def put_comparison(comparison)
-        end
+        def put_comparison(comparison); end
 
         # Swallow header output.
         #
         # @return [void]
-        def put_header
-        end
+        def put_header; end
       end
     end
   end

data/lib/benchmark/memory/job/task.rb

@@ -1,5 +1,7 @@
-require "memory_profiler"
-require "benchmark/memory/measurement"
+# frozen_string_literal: true
+
+require 'memory_profiler'
+require 'benchmark/memory/measurement'
 
 module Benchmark
   module Memory
@@ -14,7 +16,7 @@ module Benchmark
         # @raise [ArgumentError] if the action does not respond to `#call`.
         def initialize(label, action)
           unless action.respond_to?(:call)
-            fail(
+            raise(
               ArgumentError,
               "Invalid action (#{@action.inspect} does not respond to call)"
             )

data/lib/benchmark/memory/job.rb

@@ -1,9 +1,12 @@
-require "forwardable"
-require "benchmark/memory/job/task"
-require "benchmark/memory/job/io_output"
-require "benchmark/memory/job/null_output"
-require "benchmark/memory/held_results"
-require "benchmark/memory/report"
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'benchmark/memory/job/task'
+require 'benchmark/memory/job/io_output'
+require 'benchmark/memory/job/null_output'
+require 'benchmark/memory/held_results'
+require 'benchmark/memory/report'
+require 'benchmark/memory/report/comparator'
 
 module Benchmark
   module Memory
@@ -18,7 +21,6 @@ module Benchmark
       #
       # @return [Job]
       def initialize(output: $stdout, quiet: false)
-        @compare = false
         @full_report = Report.new
         @held_results = HeldResults.new
         @quiet = quiet
@@ -38,14 +40,14 @@ module Benchmark
       #
       # @return [Boolean]
       def compare?
-        @compare
+        !!@comparator
       end
 
       # Enable output of a comparison of the different tasks.
       #
       # @return [void]
-      def compare!
-        @compare = true
+      def compare!(**spec)
+        @comparator = full_report.comparator = Report::Comparator.from_spec(spec.to_h)
       end
 
       # Enable holding results to compare between separate runs.
@@ -63,10 +65,8 @@ module Benchmark
       # @param block [Proc] Code the measure.
       #
       # @raise [ArgumentError] if no code block is specified.
-      def report(label = "", &block)
-        unless block_given?
-          fail ArgumentError, "You did not specify a block for the item"
-        end
+      def report(label = '', &block)
+        raise ArgumentError, 'You did not specify a block for the item' unless block_given?
 
         tasks.push Task.new(label, block)
       end
@@ -97,21 +97,9 @@ module Benchmark
       # @return [Boolean] A flag indicating whether to hold or not.
       def run_task(task)
         if @held_results.include?(task)
-          measurement = @held_results[task.label]
-          full_report.add_entry(task, measurement)
-          return false
+          run_with_held_results(task)
         else
-          measurement = task.call
-          entry = full_report.add_entry(task, measurement)
-          @output.put_entry(entry)
-
-          if task == tasks.last
-            @held_results.cleanup
-            false
-          else
-            @held_results.add_result(entry)
-            @held_results.holding?
-          end
+          run_without_held_results(task)
         end
       end
 
@@ -119,9 +107,9 @@ module Benchmark
       #
       # @return [void]
       def run_comparison
-        if compare? && full_report.comparable?
-          @output.put_comparison(full_report.comparison)
-        end
+        return unless compare? && full_report.comparable?
+
+        @output.put_comparison(full_report.comparison)
       end
 
       # Check whether the job is set to quiet.
@@ -130,6 +118,28 @@ module Benchmark
       def quiet?
         @quiet
       end
+
+      private
+
+      def run_with_held_results(task)
+        measurement = @held_results[task.label]
+        full_report.add_entry(task, measurement)
+        false
+      end
+
+      def run_without_held_results(task)
+        measurement = task.call
+        entry = full_report.add_entry(task, measurement)
+        @output.put_entry(entry)
+
+        if task == tasks.last
+          @held_results.cleanup
+          false
+        else
+          @held_results.add_result(entry)
+          @held_results.holding?
+        end
+      end
     end
   end
 end

data/lib/benchmark/memory/measurement/metric.rb

@@ -1,12 +1,12 @@
-require "benchmark/memory/helpers"
+# frozen_string_literal: true
+
+require 'benchmark/memory/helpers'
 
 module Benchmark
   module Memory
     class Measurement
       # Describe the ratio of allocated vs. retained memory in a measurement.
       class Metric
-        include Comparable
-
         # Instantiate a Metric of allocated vs. retained memory.
         #
         # @param type [Symbol] The type of memory allocated in the metric.
@@ -26,15 +26,6 @@ module Benchmark
 
         # @return [Symbol] The type of memory allocated in the metric.
         attr_reader :type
-
-        # Sort by the total allocated.
-        #
-        # @param other [Metric] The other metric.
-        #
-        # @return [Integer]
-        def <=>(other)
-          allocated <=> other.allocated
-        end
       end
     end
   end

data/lib/benchmark/memory/measurement/metric_extractor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'benchmark/memory/measurement/metric'
+
+module Benchmark
+  module Memory
+    # Extracts metrics from a memory profiler result
+    class MetricExtractor
+      # Extracts the memory-specific metrics from a profiler result
+      #
+      # @param result [MemoryProfiler::Results]
+      # @return [Benchmark::Memory::Measurement::Metric]
+      def self.extract_memory(result)
+        Measurement::Metric.new(
+          :memsize,
+          result.total_allocated_memsize,
+          result.total_retained_memsize
+        )
+      end
+
+      # Extracts the object-specific metrics from a profiler result
+      #
+      # @param result [MemoryProfiler::Results]
+      # @return [Benchmark::Memory::Measurement::Metric]
+      def self.extract_objects(result)
+        Measurement::Metric.new(
+          :objects,
+          result.total_allocated,
+          result.total_retained
+        )
+      end
+
+      # Extracts the string-specific metrics from a profiler result
+      #
+      # @param result [MemoryProfiler::Results]
+      # @return [Benchmark::Memory::Measurement::Metric]
+      def self.extract_strings(result)
+        Measurement::Metric.new(
+          :strings,
+          result.strings_allocated.size,
+          result.strings_retained.size
+        )
+      end
+    end
+  end
+end

data/lib/benchmark/memory/measurement.rb

@@ -1,11 +1,12 @@
-require "forwardable"
-require "benchmark/memory/measurement/metric"
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'benchmark/memory/measurement/metric_extractor'
 
 module Benchmark
   module Memory
     # Encapsulate the combined metrics of an action.
     class Measurement
-      include Comparable
       include Enumerable
       extend Forwardable
 
@@ -14,23 +15,11 @@ module Benchmark
       # @param result [MemoryProfiler::Results]
       #   The results of a MemoryProfiler report.
       def self.from_result(result)
-        memory = Metric.new(
-          :memsize,
-          result.total_allocated_memsize,
-          result.total_retained_memsize
-        )
-        objects = Metric.new(
-          :objects,
-          result.total_allocated,
-          result.total_retained
-        )
-        strings = Metric.new(
-          :strings,
-          result.strings_allocated.size,
-          result.strings_retained.size
-        )
+        memory = MetricExtractor.extract_memory(result)
+        objects = MetricExtractor.extract_objects(result)
+        strings = MetricExtractor.extract_strings(result)
 
-        new(:memory => memory, :objects => objects, :strings => strings)
+        new(memory: memory, objects: objects, strings: strings)
       end
 
       # Instantiate a Measurement of memory usage.
@@ -59,22 +48,6 @@ module Benchmark
 
       # Enumerate through the metrics when enumerating a measurement.
       def_delegator :metrics, :each
-
-      # Compare two measurements for sorting purposes.
-      #
-      # @param other [Measurement] The other measurement
-      #
-      # @return [Integer]
-      def <=>(other)
-        memory <=> other.memory
-      end
-
-      # Total amount of allocated memory for the measurement.
-      #
-      # @return [Integer]
-      def allocated_memory
-        memory.allocated
-      end
     end
   end
 end

data/lib/benchmark/memory/report/comparator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Benchmark
+  module Memory
+    class Report
+      # Compares two {Entry} for the purposes of sorting and outputting a {Comparison}.
+      class Comparator
+        # @private
+        METRICS = %i[memory objects strings].freeze
+
+        # @private
+        VALUES  = %i[allocated retained].freeze
+
+        # Instantiates a {Comparator} from a spec given by {Job#compare!}
+        #
+        # @param spec [Hash<Symbol, Symbol>] The specification given for the {Comparator}
+        # @return [Comparator]
+        def self.from_spec(spec)
+          raise ArgumentError, 'Only send a single metric and value, in the form memory: :allocated' if spec.length > 1
+
+          metric, value = *spec.first
+          metric ||= :memory
+          value  ||= :allocated
+
+          new(metric: metric, value: value)
+        end
+
+        # Instantiate a new comparator
+        #
+        # @param metric [Symbol] (see #metric)
+        # @param value [Symbol] (see #value)
+        def initialize(metric: :memory, value: :allocated)
+          raise ArgumentError, "Invalid metric: #{metric.inspect}" unless METRICS.include? metric
+          raise ArgumentError, "Invalid value: #{value.inspect}" unless VALUES.include? value
+
+          @metric = metric
+          @value = value
+        end
+
+        # @return [Symbol] The metric to compare, one of `:memory`, `:objects`, or `:strings`
+        attr_reader :metric
+
+        # @return [Symbol] The value to compare, one of `:allocated` or `:retained`
+        attr_reader :value
+
+        # Checks whether a {Comparator} equals another
+        #
+        # @param other [Benchmark::Memory::Comparator] The comparator to check against
+        #
+        # @return [Boolean]
+        def ==(other)
+          metric == other.metric && value == other.value
+        end
+
+        # Converts the {Comparator} to a Proc for passing to a block
+        #
+        # @return [Proc]
+        def to_proc
+          proc { |entry| entry.measurement.public_send(metric).public_send(value) }
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/report/comparison.rb

@@ -1,18 +1,33 @@
+# frozen_string_literal: true
+
 module Benchmark
   module Memory
     class Report
       # Compare entries against each other.
       class Comparison
+        extend Forwardable
+
         # Instantiate a new comparison.
         #
         # @param entries [Array<Entry>] The entries to compare.
-        def initialize(entries)
-          @entries = entries.sort_by(&:measurement)
+        # @param comparator [Comparator] The comparator to use when generating.
+        def initialize(entries, comparator)
+          @entries = entries.sort_by(&comparator)
+          @comparator = comparator
         end
 
+        # @return [Comparator] The {Comparator} to use when generating the {Comparison}.
+        attr_reader :comparator
+
         # @return [Array<Entry>] The entries to compare.
         attr_reader :entries
 
+        # @!method metric
+        #   @return [Symbol] The metric to compare, one of `:memory`, `:objects`, or `:strings`
+        # @!method value
+        #   @return [Symbol] The value to compare, one of `:allocated` or `:retained`
+        def_delegators :@comparator, :metric, :value
+
         # Check if the comparison is possible
         #
         # @return [Boolean]

data/lib/benchmark/memory/report/entry.rb

@@ -1,4 +1,6 @@
-require "forwardable"
+# frozen_string_literal: true
+
+require 'forwardable'
 
 module Benchmark
   module Memory
@@ -22,9 +24,10 @@ module Benchmark
 
         # Get the total amount of memory allocated in the entry.
         #
+        # @param comparison [Comparison] The {Comparison} to compare.
         # @return [Integer]
-        def allocated_memory
-          measurement.memory.allocated
+        def compared_metric(comparison)
+          measurement.public_send(comparison.metric).public_send(comparison.value)
         end
       end
     end

data/lib/benchmark/memory/report.rb

@@ -1,5 +1,7 @@
-require "benchmark/memory/report/comparison"
-require "benchmark/memory/report/entry"
+# frozen_string_literal: true
+
+require 'benchmark/memory/report/comparison'
+require 'benchmark/memory/report/entry'
 
 module Benchmark
   module Memory
@@ -10,8 +12,12 @@ module Benchmark
       # @return [Report]
       def initialize
         @entries = []
+        @comparator = Comparator.new
       end
 
+      # @return [Comparator] The {Comparator} to use when creating the {Comparison}.
+      attr_accessor :comparator
+
       # @return [Array<Entry>] The entries in the report.
       attr_reader :entries
 
@@ -38,7 +44,7 @@ module Benchmark
       #
       # @return [Comparison]
       def comparison
-        @comparison ||= Comparison.new(entries)
+        @comparison ||= Comparison.new(entries, comparator)
       end
     end
   end

data/lib/benchmark/memory/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Benchmark
   module Memory
-    VERSION = "0.1.2".freeze
+    VERSION = '0.2.0'
   end
 end

data/lib/benchmark/memory.rb

@@ -1,6 +1,8 @@
-require "benchmark/memory/errors"
-require "benchmark/memory/job"
-require "benchmark/memory/version"
+# frozen_string_literal: true
+
+require 'benchmark/memory/errors'
+require 'benchmark/memory/job'
+require 'benchmark/memory/version'
 
 # Performance benchmarking library
 module Benchmark
@@ -13,14 +15,9 @@ module Benchmark
     #
     # @return [Report]
     def memory(quiet: false)
-      unless block_given?
-        fail(
-          ConfigurationError,
-          "You did not give a test block to your call to `Benchmark.memory`"
-        )
-      end
+      raise ConfigurationError unless block_given?
 
-      job = Job.new(:quiet => quiet)
+      job = Job.new(quiet: quiet)
 
       yield job
 

data/lib/benchmark-memory.rb

@@ -1,2 +1,3 @@
-# rubocop:disable Style/FileName
-require "benchmark/memory"
+# frozen_string_literal: true
+
+require 'benchmark/memory'