benchmark-memory 0.1.0

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

@@ -0,0 +1,39 @@
+require "benchmark/memory/helpers"
+require "benchmark/memory/job/io_output/metric_formatter"
+
+module Benchmark
+  module Memory
+    class Job
+      class IOOutput
+        # Format entries for use with the IOOutput.
+        class EntryFormatter
+          include Helpers
+
+          # Instantiate a formatter to output an entry into an IO.
+          #
+          # @param entry [Entry] The entry to format.
+          def initialize(entry)
+            @entry = entry
+          end
+
+          # @return [Entry] The entry to format.
+          attr_reader :entry
+
+          # Format entry to a string to put on the output.
+          #
+          # @return [String]
+          def to_s
+            output = StringIO.new
+            output << rjust(entry.label)
+            entry.measurement.each_with_index.map do |metric, index|
+              output << " " * 20 unless index == 0
+              output << MetricFormatter.new(metric)
+              output << "\n"
+            end
+            output.string
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require "benchmark/memory/helpers"
+
+module Benchmark
+  module Memory
+    class Job
+      class IOOutput
+        # Format metrics for use with the IOOutput.
+        class MetricFormatter
+          include Helpers
+
+          # Instantiate a formatter to output a metric into an IO.
+          #
+          # @param metric [Measurement::Metric] The metric to format.
+          def initialize(metric)
+            @metric = metric
+          end
+
+          # @return [Metric] The metric to format.
+          attr_reader :metric
+
+          # Format metric to a string to put on the output.
+          #
+          # @return [String]
+          def to_s
+            [
+              format("%s %s", scale(metric.allocated), metric.type),
+              format("(%s retained)", scale(metric.retained)),
+            ].join(" ")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Benchmark
+  module Memory
+    class Job
+      # Swallow all output from a job.
+      class NullOutput
+        # Swallow entry output.
+        #
+        # @return [void]
+        def put_entry(entry)
+        end
+
+        # Swallow comparison output.
+        #
+        # @return [void]
+        def put_comparison(comparison)
+        end
+
+        # Swallow header output.
+        #
+        # @return [void]
+        def put_header
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+require "memory_profiler"
+require "benchmark/memory/measurement"
+
+module Benchmark
+  module Memory
+    class Job
+      # Hold a labelled job for later measurement.
+      class Task
+        # Instantiate a job task for later measurement.
+        #
+        # @param label [#to_s] The label for the benchmark.
+        # @param action [#call] The code to be measured.
+        #
+        # @raise [ArgumentError] if the action does not respond to `#call`.
+        def initialize(label, action)
+          unless action.respond_to?(:call)
+            fail(
+              ArgumentError,
+              "Invalid action (#{@action.inspect} does not respond to call)"
+            )
+          end
+
+          @label = label
+          @action = action
+        end
+
+        # @return [#call] The code to be measured.
+        attr_reader :action
+
+        # @return [#to_s] The label for the benchmark.
+        attr_reader :label
+
+        # Call the action and report on its memory usage.
+        #
+        # @return [Measurement] the memory usage measurement of the code.
+        def call
+          result = while_measuring_memory_usage { action.call }
+
+          Measurement.from_result(result)
+        end
+
+        private
+
+        def while_measuring_memory_usage(&block)
+          MemoryProfiler.report({}, &block)
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/measurement.rb

@@ -0,0 +1,80 @@
+require "forwardable"
+require "benchmark/memory/measurement/metric"
+
+module Benchmark
+  module Memory
+    # Encapsulate the combined metrics of an action.
+    class Measurement
+      include Comparable
+      include Enumerable
+      extend Forwardable
+
+      # Create a Measurement from a MemoryProfiler::Results object.
+      #
+      # @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
+        )
+
+        new(:memory => memory, :objects => objects, :strings => strings)
+      end
+
+      # Instantiate a Measurement of memory usage.
+      #
+      # @param memory [Metric] The memory usage of an action.
+      # @param objects [Metric] The object allocations of an action.
+      # @param strings [Metric] The string allocations of an action.
+      def initialize(memory:, objects:, strings:)
+        @memory = memory
+        @objects = objects
+        @strings = strings
+        @metrics = [@memory, @objects, @strings]
+      end
+
+      # @return [Metric] The memory allocation metric.
+      attr_reader :memory
+
+      # @return [Array<Metric>] The metrics for the measurement.
+      attr_reader :metrics
+
+      # @return [Metric] The object allocation metric.
+      attr_reader :objects
+
+      # @return [Metric] The string allocation metric.
+      attr_reader :strings
+
+      # 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/measurement/metric.rb

@@ -0,0 +1,41 @@
+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.
+        # @param allocated [Integer] The amount allocated in the metric.
+        # @param retained [Integer] The amount retained in the metric.
+        def initialize(type, allocated, retained)
+          @type = type
+          @allocated = allocated
+          @retained = retained
+        end
+
+        # @return [Integer] The amount allocated in the metric.
+        attr_reader :allocated
+
+        # @return [Integer] The amount retained in the metric.
+        attr_reader :retained
+
+        # @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
+end

data/lib/benchmark/memory/report.rb

@@ -0,0 +1,45 @@
+require "benchmark/memory/report/comparison"
+require "benchmark/memory/report/entry"
+
+module Benchmark
+  module Memory
+    # Hold the results of a set of benchmarks.
+    class Report
+      # Instantiate a report to hold entries of tasks and measurements.
+      #
+      # @return [Report]
+      def initialize
+        @entries = []
+      end
+
+      # @return [Array<Entry>] The entries in the report.
+      attr_reader :entries
+
+      # Add an entry to the report.
+      #
+      # @param task [Job::Task] The task to report about.
+      # @param measurement [Measurement] The measurements from the task.
+      #
+      # @return [Entry] the newly created entry.
+      def add_entry(task, measurement)
+        entry = Entry.new(task.label, measurement)
+        entries.push(entry)
+        entry
+      end
+
+      # Return true if the report is comparable.
+      #
+      # @return [Boolean]
+      def comparable?
+        comparison.possible?
+      end
+
+      # Compare the entries within a report.
+      #
+      # @return [Comparison]
+      def comparison
+        @comparison ||= Comparison.new(entries)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Benchmark
+  module Memory
+    class Report
+      # Compare entries against each other.
+      class Comparison
+        # Instantiate a new comparison.
+        #
+        # @param entries [Array<Entry>] The entries to compare.
+        def initialize(entries)
+          @entries = entries.sort_by(&:measurement)
+        end
+
+        # @return [Array<Entry>] The entries to compare.
+        attr_reader :entries
+
+        # Check if the comparison is possible
+        #
+        # @return [Boolean]
+        def possible?
+          entries.size > 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+require "forwardable"
+
+module Benchmark
+  module Memory
+    class Report
+      # An entry in a report about a benchmark.
+      class Entry
+        # Instantiate a new entry.
+        #
+        # @param label [#to_s] The entry label.
+        # @param measurement [Measurement] The measurements for the entry.
+        def initialize(label, measurement)
+          @label = label
+          @measurement = measurement
+        end
+
+        # @return [#to_s] The entry label.
+        attr_reader :label
+
+        # @return [Measurement] The measurements for the entry.
+        attr_reader :measurement
+
+        # Get the total amount of memory allocated in the entry.
+        #
+        # @return [Integer]
+        def allocated_memory
+          measurement.memory.allocated
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/memory/version.rb

@@ -0,0 +1,5 @@
+module Benchmark
+  module Memory
+    VERSION = "0.1.0".freeze
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: benchmark-memory
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: memory_profiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+description: Benchmark-style memory profiling for Ruby 2.1+
+email:
+- michael.j.herold@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- Rakefile
+- benchmark-memory.gemspec
+- lib/benchmark-memory.rb
+- lib/benchmark/memory.rb
+- lib/benchmark/memory/errors.rb
+- lib/benchmark/memory/held_results.rb
+- lib/benchmark/memory/held_results/entry_serializer.rb
+- lib/benchmark/memory/held_results/measurement_serializer.rb
+- lib/benchmark/memory/held_results/metric_serializer.rb
+- lib/benchmark/memory/held_results/serializer.rb
+- lib/benchmark/memory/helpers.rb
+- lib/benchmark/memory/job.rb
+- lib/benchmark/memory/job/io_output.rb
+- lib/benchmark/memory/job/io_output/comparison_formatter.rb
+- lib/benchmark/memory/job/io_output/entry_formatter.rb
+- lib/benchmark/memory/job/io_output/metric_formatter.rb
+- lib/benchmark/memory/job/null_output.rb
+- lib/benchmark/memory/job/task.rb
+- lib/benchmark/memory/measurement.rb
+- lib/benchmark/memory/measurement/metric.rb
+- lib/benchmark/memory/report.rb
+- lib/benchmark/memory/report/comparison.rb
+- lib/benchmark/memory/report/entry.rb
+- lib/benchmark/memory/version.rb
+homepage: https://github.com/michaelherold/benchmark-memory
+licenses:
+- MIT
+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.5.1
+signing_key: 
+specification_version: 4
+summary: Benchmark-style memory profiling for Ruby 2.1+
+test_files: []
+has_rdoc: