benchmark-memory 0.1.0

data/lib/benchmark/memory/held_results/entry_serializer.rb

@@ -0,0 +1,35 @@
+require "benchmark/memory/held_results/serializer"
+require "benchmark/memory/held_results/measurement_serializer"
+require "benchmark/memory/report/entry"
+
+module Benchmark
+  module Memory
+    class HeldResults
+      # Serialize entrys for holding between runs.
+      class EntrySerializer < Serializer
+        # Convert a JSON hash into an Entry.
+        #
+        # @param hash [Hash] A JSON document hash.
+        #
+        # @return [Report::Entry]
+        def load(hash)
+          @object = Report::Entry.new(
+            hash["item"],
+            MeasurementSerializer.load(hash["measurement"])
+          )
+          self
+        end
+
+        # Convert the entry to a Hash.
+        #
+        # @return [Hash] The entry as a Hash.
+        def to_h
+          {
+            :item        => object.label,
+            :measurement => MeasurementSerializer.new(object.measurement).to_h,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/held_results/measurement_serializer.rb

@@ -0,0 +1,37 @@
+require "benchmark/memory/held_results/serializer"
+require "benchmark/memory/held_results/metric_serializer"
+require "benchmark/memory/measurement"
+
+module Benchmark
+  module Memory
+    class HeldResults
+      # Serialize measurements for holding between runs.
+      class MeasurementSerializer < Serializer
+        # Convert a JSON hash into a Measurement.
+        #
+        # @param hash [Hash] A JSON document hash.
+        #
+        # @return [Measurement]
+        def load(hash)
+          @object = Measurement.new(
+            :memory => MetricSerializer.load(hash["memory"]),
+            :objects => MetricSerializer.load(hash["objects"]),
+            :strings => MetricSerializer.load(hash["strings"])
+          )
+          self
+        end
+
+        # Convert the measurement to a Hash.
+        #
+        # @return [Hash] The measurement as a Hash.
+        def to_h
+          {
+            :memory  => MetricSerializer.new(object.memory).to_h,
+            :objects => MetricSerializer.new(object.objects).to_h,
+            :strings => MetricSerializer.new(object.strings).to_h,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/held_results/metric_serializer.rb

@@ -0,0 +1,37 @@
+require "benchmark/memory/held_results/serializer"
+require "benchmark/memory/measurement/metric"
+
+module Benchmark
+  module Memory
+    class HeldResults
+      # Serialize metrics for holding between runs.
+      class MetricSerializer < Serializer
+        # Convert a JSON hash into a Metric.
+        #
+        # @param hash [Hash] A JSON document hash.
+        #
+        # @return [Measurement::Metric]
+        #
+        def load(hash)
+          @object = Measurement::Metric.new(
+            hash["type"],
+            hash["allocated"],
+            hash["retained"]
+          )
+          self
+        end
+
+        # Convert the metric to a Hash.
+        #
+        # @return [Hash] The metric as a Hash.
+        def to_h
+          {
+            :allocated => object.allocated,
+            :retained  => object.retained,
+            :type      => object.type,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/held_results/serializer.rb

@@ -0,0 +1,64 @@
+require "json"
+
+module Benchmark
+  module Memory
+    class HeldResults
+      # Serialize objects for holding between runs.
+      class Serializer
+        # Load an object from a JSON document.
+        #
+        # @param json [String] A JSON document as a string.
+        #
+        # @return [Object] The object converted from the JSON document.
+        def self.load(json)
+          json = JSON.parse(json) if json.is_a?(String)
+          new.load(json).object
+        end
+
+        # Instantiate a new serializer.
+        #
+        # @param object [Object] The object to serialize.
+        def initialize(object = nil)
+          @object = object
+        end
+
+        # @return [Object] The object to serialize.
+        attr_reader :object
+
+        # Convert a JSON document into an object.
+        #
+        # @param _hash [Hash] A JSON document hash.
+        #
+        # @return [Object]
+        # @raise [NotImplementedError]
+        #   If the inheriting subclass didn't implement.
+        def load(_hash)
+          fail(
+            NotImplementedError,
+            "You must implement a concrete version in a subclass"
+          )
+        end
+
+        # Convert the object to a Hash.
+        #
+        # @return [Hash] The object as a Hash.
+        # @raise [NotImplementedError]
+        #   If the inheriting subclass didn't implement.
+        def to_h
+          fail(
+            NotImplementedError,
+            "You must implement a concrete version in a subclass"
+          )
+        end
+
+        # Convert the object to a JSON document.
+        #
+        # @return [String] The object as a JSON document.
+        def to_json
+          JSON.generate(to_h)
+        end
+        alias_method :to_s, :to_json
+      end
+    end
+  end
+end

data/lib/benchmark/memory/helpers.rb

@@ -0,0 +1,46 @@
+module Benchmark
+  module Memory
+    # Helper methods for formatting output.
+    module Helpers
+      # Right-justifies to a length of 20 or adds a line of padding when longer.
+      #
+      # @param label [#to_s] The label to justify.
+      #
+      # @return [String] The justified label.
+      def rjust(label)
+        label = label.to_s
+
+        if label.size > 20
+          "#{label}\n#{' ' * 20}"
+        else
+          label.rjust(20)
+        end
+      end
+
+      # Scale a value into human-understandable terms.
+      #
+      # @param value [Integer, Float] The value to scale.
+      #
+      # @return [String] The scaled value.
+      def scale(value)
+        scale = Math.log10(value)
+        scale = 0 if scale.infinite?
+        scale = (scale / 3).to_i
+        suffix =
+          case scale
+          when 1 then "k"
+          when 2 then "M"
+          when 3 then "B"
+          when 4 then "T"
+          when 5 then "Q"
+          else
+            scale = 0
+            " "
+          end
+
+        format("%10.3f#{suffix}", value.to_f / (1000**scale))
+      end
+      module_function :scale
+    end
+  end
+end

data/lib/benchmark/memory/job.rb

@@ -0,0 +1,135 @@
+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"
+
+module Benchmark
+  module Memory
+    # Encapsulate the memory measurements of reports.
+    class Job
+      extend Forwardable
+
+      # Instantiate a job for containing memory performance reports.
+      #
+      # @param output [#puts] The output to use for showing the job results.
+      # @param quiet [Boolean] A flag for stopping output.
+      #
+      # @return [Job]
+      def initialize(output: $stdout, quiet: false)
+        @compare = false
+        @full_report = Report.new
+        @held_results = HeldResults.new
+        @quiet = quiet
+        @output = quiet? ? NullOutput.new : IOOutput.new(output)
+        @tasks = []
+      end
+
+      # @return [Report] the full report of all measurements in the job.
+      attr_reader :full_report
+
+      # @return [Array<Task>] the measurement tasks to run.
+      attr_reader :tasks
+
+      def_delegator :@held_results, :holding?
+
+      # Check whether the job should do a comparison.
+      #
+      # @return [Boolean]
+      def compare?
+        @compare
+      end
+
+      # Enable output of a comparison of the different tasks.
+      #
+      # @return [void]
+      def compare!
+        @compare = true
+      end
+
+      # Enable holding results to compare between separate runs.
+      #
+      # @param held_path [String, IO] The location to save the held results.
+      #
+      # @return [void]
+      def hold!(held_path)
+        @held_results.path = held_path
+      end
+
+      # Add a measurement entry to the job to measure the specified block.
+      #
+      # @param label [String] The label for the measured code.
+      # @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
+
+        tasks.push Task.new(label, block)
+      end
+
+      # Run the job and outputs its full report.
+      #
+      # @return [Report]
+      def run
+        @output.put_header
+        @held_results.load
+
+        tasks.each do |task|
+          held = run_task(task)
+
+          if held
+            @output.put_hold_notice
+            break
+          end
+        end
+
+        full_report
+      end
+
+      # Run a task.
+      #
+      # @param task [Task]
+      #
+      # @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
+        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
+        end
+      end
+
+      # Run a comparison of the entries and puts it on the output.
+      #
+      # @return [void]
+      def run_comparison
+        if compare? && full_report.comparable?
+          @output.put_comparison(full_report.comparison)
+        end
+      end
+
+      # Check whether the job is set to quiet.
+      #
+      # @return [Boolean]
+      def quiet?
+        @quiet
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+require "benchmark/memory/job/io_output/comparison_formatter"
+require "benchmark/memory/job/io_output/entry_formatter"
+
+module Benchmark
+  module Memory
+    class Job
+      # Output the results of jobs into an IO.
+      class IOOutput
+        # Instantiate a new output that writes to an IO.
+        #
+        # @param io [#puts] The IO to write on.
+        def initialize(io)
+          @io = io
+        end
+
+        # Put the entry onto the output.
+        #
+        # @return [void]
+        def put_entry(entry)
+          @io.puts EntryFormatter.new(entry)
+        end
+
+        # Put the comparison onto the output.
+        #
+        # @return [void]
+        def put_comparison(comparison)
+          @io.puts
+          @io.puts "Comparison:"
+          @io.puts ComparisonFormatter.new(comparison)
+        end
+
+        # Put the header onto the output.
+        #
+        # @return [void]
+        def put_header
+          @io.puts "Calculating -------------------------------------"
+        end
+
+        # Put a notice that the execution is holding for another run.
+        #
+        # @return [void]
+        def put_hold_notice
+          @io.puts
+          @io.puts "Pausing here -- run Ruby again to " \
+                   "measure the next benchmark..."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+require "benchmark/memory/helpers"
+require "benchmark/memory/job/io_output/metric_formatter"
+
+module Benchmark
+  module Memory
+    class Job
+      class IOOutput
+        # Format a comparison for use with the IOOutput.
+        class ComparisonFormatter
+          include Helpers
+
+          # Instantiate a formatter to output an comparison into an IO.
+          #
+          # @param comparison [Report::Comparison] The comparison to format.
+          def initialize(comparison)
+            @comparison = comparison
+          end
+
+          # @return [Report::Comparison] The comparison to format.
+          attr_reader :comparison
+
+          # Format comparison to a string to put on the output.
+          #
+          # @return [String]
+          def to_s
+            return "" unless comparison.possible?
+
+            output = StringIO.new
+            best, rest = *comparison.entries
+            rest = Array(rest)
+
+            add_best_summary(best, output)
+
+            rest.each do |entry|
+              add_comparison(entry, best, output)
+            end
+
+            output.string
+          end
+
+          private
+
+          def add_best_summary(best, output)
+            output << summary_message("%20s: %10i allocated\n", best)
+          end
+
+          def add_comparison(entry, best, output)
+            output << summary_message("%20s: %10i allocated - ", entry)
+            output << comparison_between(entry, best)
+          end
+
+          def comparison_between(entry, best)
+            ratio = entry.allocated_memory.to_f / best.allocated_memory.to_f
+
+            if ratio.abs > 1
+              format("%.2fx more", ratio)
+            else
+              "same"
+            end
+          end
+
+          def summary_message(message, entry)
+            format(message, entry.label, entry.allocated_memory)
+          end
+        end
+      end
+    end
+  end
+end