ruby_memcheck 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 84b08d7b0d1f0f1a254be4d2634c44055c21c415ccfa12d69c9bef56763291bf
+  data.tar.gz: b73189e2d75124b4117565ba97a2fadf1a1b8ef9963bf6d8528fb04bd19c0b33
+SHA512:
+  metadata.gz: 682b181ca12116b0383a317304e9f931b4ccc4459259ef87b5d7823641ae73ec1077954e0a80b704ee20d525d39f01ea12ded58e24e39c48e69a065e79811873
+  data.tar.gz: 82ea0151eebe57bcc43cc7316ba93ad6bb8af5413c311ffd48d78ebf105091774a1c28364a8acef7b4dafcfb4cc21fa4a542f43457bda44a69b8f63b9294f177

data/.github/workflows/lint.yml

@@ -0,0 +1,12 @@
+name: Lint
+on: [push, pull_request]
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+      - run: bundle install --jobs=3 --retry=3 --path=vendor/bundle
+      - run: bundle exec rubocop

data/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        entry:
+          - { ruby: '2.6', allowed-failure: false }
+          - { ruby: '2.7', allowed-failure: false }
+          - { ruby: '3.0', allowed-failure: false }
+          - { ruby: ruby-head, allowed-failure: false }
+    name: ruby ${{ matrix.entry.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.entry.ruby }}
+      - run: sudo apt-get install -y valgrind
+      - run: bundle install --jobs=3 --retry=3
+      - run: bundle exec rake
+        continue-on-error: ${{ matrix.entry.allowed-failure }}

data/.gitignore

@@ -0,0 +1,12 @@
+Gemfile.lock
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+*.so

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+AllCops:
+  SuggestExtensions: false

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Peter Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,97 @@
+# ruby_memcheck
+
+This gem provides a sane way to use Valgrind's memcheck on your native extension gem.
+
+## Table of contents
+
+1. [What is this gem?](#what-is-this-gem)
+    1. [Who should use this gem?](#who-should-use-this-gem)
+    1. [How does it work?](#how-does-it-work)
+    1. [Limitations](#limitations)
+1. [Installation](#installation)
+1. [Usage](#usage)
+
+## What is this gem?
+
+Valgrind's memcheck is a great tool to find and debug memory issues (e.g. memory leak, use-after-free, etc.). However, it doesn't work well on Ruby because Ruby does not free all of the memory it allocates during shutdown. This results in Valgrind reporting thousands (or more) false-positives, making it very difficult for Valgrind to actually be useful. This gem solves the problem by using heuristics to filter out false-positives.
+
+### Who should use this gem?
+
+Only gems with native extensions can use this gem. If your gem is written in plain Ruby, this gem is not useful for you.
+
+### How does it work?
+
+This gem runs Valgrind with the `--xml` option to generate a XML of all the errors. It will then parse the XML and use various heuristics based on the type of the error and the stack trace to filter out errors that are false-positives.
+
+### Limitations
+
+Because of the aggressive heuristics used to filter out false-positives, there are various limitations of what this gem can detect.
+
+1. This gem is only expected to work on Linux.
+1. It will not find memory leaks in Ruby. It filters out everything in Ruby.
+1. It will not find memory leaks of allocations that occurred in Ruby (even if the memory leak is caused by your native extension).
+
+    An example of this is if a string is allocated in Ruby, passed into your native extension, you change the pointer of the string without freeing the contents, so the contents of the string becomes leaked.
+1. To filter out false-positives, it will only find definite leaks (i.e. memory regions with no pointers to it). It will not find possible leaks (i.e. memory regions with pointers to it).
+1. It will not find leaks that occur in the `Init` function of your native extension.
+1. It will not find uses of undefined values (e.g. conditional jumps depending on undefined values). This is just a technical limitation that has not been solved yet (contributions welcome!).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ruby_memcheck"
+```
+
+## Usage
+
+The easiest way to use this gem is to use it on your test suite using rake.
+
+0. Install Valgrind.
+1. In your Rakefile, require this gem.
+
+    ```ruby
+    require "ruby_memcheck"
+    ```
+1. Configure the gem by calling `RubyMemcheck.config`. You must pass it your binary name. This is the same value you passed into `create_makefile` in your `extconf.rb` file. Make sure this value is correct or it will filter out almost everything as a false-positive!
+
+    ```ruby
+    RubyMemcheck.config(binary_name: "your_binary_name")
+    ```
+1. Locate your test task(s) in your Rakefile. You can identify it with a call to `Rake::TestTask.new`.
+1. Create a namespace under the test task and create a `RubyMemcheck::TestTask` with the same configuration.
+
+    For example, if your Rakefile looked like this before:
+
+    ```ruby
+    Rake::TestTask.new(test: :compile) do |t|
+      t.libs << "test"
+      t.test_files = FileList["test/unit/**/*_test.rb"]
+    end
+    ```
+
+    You can change it to look like this:
+
+    ```ruby
+    test_config = lambda do |t|
+      t.libs << "test"
+      t.test_files = FileList["test/**/*_test.rb"]
+    end
+    Rake::TestTask.new(test: :compile, &test_config)
+    namespace :test do
+      RubyMemcheck::TestTask.new(valgrind: :compile, &test_config)
+    end
+    ```
+1. In your `test_helper.rb`/`spec_helper.rb` (or whatever file sets up your test suite), add this line:
+
+    ```ruby
+    END { GC.start }
+    ```
+
+    This will ensure that the Garbage Collector is ran before Ruby shuts down. This will reduce the number of false-positives.
+1. You're ready to run your test suite with Valgrind using `rake test:valgrind`! Note that this will take a while to run because Valgrind will make Ruby significantly slower.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rake/extensiontask"
+
+Rake::TestTask.new(test: "test:compile") do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+namespace :test do
+  Rake::ExtensionTask.new("ruby_memcheck_c_test") do |ext|
+    ext.ext_dir = "test/ruby_memcheck/ext"
+    ext.lib_dir = "test/ruby_memcheck/ext"
+  end
+end
+
+task default: :test

data/lib/ruby_memcheck/configuration.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  class Configuration
+    DEFAULT_VALGRIND = "valgrind"
+    DEFAULT_VALGRIND_OPTIONS = [
+      "--num-callers=50",
+      "--error-limit=no",
+      "--undef-value-errors=no",
+      "--leak-check=full",
+      "--show-leak-kinds=definite",
+    ].freeze
+    DEFAULT_SKIPPED_RUBY_FUNCTIONS = [
+      /\Arb_check_funcall/,
+      /\Arb_enc_raise\z/,
+      /\Arb_funcall/,
+      /\Arb_ivar_set\z/,
+      /\Arb_raise\z/,
+      /\Arb_rescue/,
+      /\Arb_respond_to\z/,
+      /\Arb_yield/,
+    ].freeze
+
+    attr_reader :binary_name, :ruby, :valgrind_options, :valgrind,
+      :skipped_ruby_functions, :valgrind_xml_file, :output_io
+
+    def initialize(
+      binary_name:,
+      ruby: FileUtils::RUBY,
+      valgrind: DEFAULT_VALGRIND,
+      valgrind_options: DEFAULT_VALGRIND_OPTIONS,
+      skipped_ruby_functions: DEFAULT_SKIPPED_RUBY_FUNCTIONS,
+      valgrind_xml_file: Tempfile.new,
+      output_io: $stderr
+    )
+      @binary_name = binary_name
+      @ruby = ruby
+      @valgrind = valgrind
+      @valgrind_options = valgrind_options
+      @skipped_ruby_functions = skipped_ruby_functions
+      @output_io = output_io
+
+      if valgrind_xml_file
+        @valgrind_xml_file = valgrind_xml_file
+        @valgrind_options += [
+          "--xml=yes",
+          "--xml-file=#{valgrind_xml_file.path}",
+        ]
+      end
+    end
+
+    def command(*args)
+      "#{valgrind} #{valgrind_options.join(" ")} #{ruby} #{args.join(" ")}"
+    end
+
+    def skip_stack?(stack)
+      in_binary = false
+
+      stack.frames.each do |frame|
+        fn = frame.fn
+
+        if frame_in_ruby?(frame) # in ruby
+          unless in_binary
+            # Skip this stack because it was called from Ruby
+            return true if skipped_ruby_functions.any? { |r| r.match?(fn) }
+          end
+        elsif frame_in_binary?(frame) # in binary
+          in_binary = true
+
+          # Skip the Init function
+          return true if fn == "Init_#{binary_name}"
+        end
+      end
+
+      !in_binary
+    end
+
+    def frame_in_ruby?(frame)
+      frame.obj == ruby
+    end
+
+    def frame_in_binary?(frame)
+      if frame.obj
+        File.basename(frame.obj, ".*") == binary_name
+      else
+        false
+      end
+    end
+  end
+end

data/lib/ruby_memcheck/frame.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  class Frame
+    attr_reader :fn, :obj, :file, :line, :in_binary
+    alias_method :in_binary?, :in_binary
+
+    def initialize(configuration, frame_xml)
+      @fn = frame_xml.at_xpath("fn")&.content
+      @obj = frame_xml.at_xpath("obj")&.content
+      # file and line may not be available
+      @file = frame_xml.at_xpath("file")&.content
+      @line = frame_xml.at_xpath("line")&.content
+
+      @in_binary = configuration.frame_in_binary?(self)
+    end
+
+    def to_s
+      if file
+        "#{fn} (#{file}:#{line})"
+      elsif fn
+        "#{fn} (at #{obj})"
+      else
+        "<unknown stack frame>"
+      end
+    end
+  end
+end

data/lib/ruby_memcheck/stack.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  class Stack
+    attr_reader :frames
+
+    def initialize(configuration, stack_xml)
+      @frames = stack_xml.xpath("frame").map { |frame| Frame.new(configuration, frame) }
+    end
+  end
+end

data/lib/ruby_memcheck/test_task.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  class TestTask < Rake::TestTask
+    VALGRIND_REPORT_MSG = "Valgrind reported errors (e.g. memory leak or use-after-free)"
+
+    attr_reader :configuration, :errors
+
+    def initialize(*args)
+      @configuration =
+        if !args.empty? && args[0].is_a?(Configuration)
+          args.shift
+        else
+          RubyMemcheck.default_configuration
+        end
+
+      super
+    end
+
+    def ruby(*args, **options, &block)
+      command = configuration.command(args)
+      sh(command, **options) do |ok, res|
+        if ok && configuration.valgrind_xml_file
+          parse_valgrind_output
+          unless errors.empty?
+            output_valgrind_errors
+            raise VALGRIND_REPORT_MSG
+          end
+        end
+
+        yield ok, res if block_given?
+      end
+    end
+
+    private
+
+    def parse_valgrind_output
+      @errors = []
+
+      xml = Nokogiri::XML(configuration.valgrind_xml_file.read)
+      xml.xpath("/valgrindoutput/error").each do |error|
+        error = ValgrindError.new(configuration, error)
+        next if error.skip?
+        @errors << error
+      end
+    end
+
+    def output_valgrind_errors
+      @errors.each do |error|
+        configuration.output_io.puts error
+        configuration.output_io.puts
+      end
+    end
+  end
+end

data/lib/ruby_memcheck/valgrind_error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  class ValgrindError
+    attr_reader :kind, :msg, :stack
+
+    def initialize(configuration, error)
+      @kind = error.at_xpath("kind").content
+      @msg =
+        if kind_leak?
+          error.at_xpath("xwhat/text").content
+        else
+          error.at_xpath("what").content
+        end
+      @stack = Stack.new(configuration, error.at_xpath("stack"))
+      @configuration = configuration
+    end
+
+    def skip?
+      if should_filter?
+        @configuration.skip_stack?(stack)
+      else
+        false
+      end
+    end
+
+    def to_s
+      str = StringIO.new
+      str << "#{msg}\n"
+      stack.frames.each do |frame|
+        str << if frame.in_binary?
+          " *#{frame}\n"
+        else
+          "  #{frame}\n"
+        end
+      end
+      str.string
+    end
+
+    private
+
+    def should_filter?
+      kind_leak?
+    end
+
+    def kind_leak?
+      kind.start_with?("Leak_")
+    end
+  end
+end

data/lib/ruby_memcheck/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyMemcheck
+  VERSION = "0.1.0"
+end

data/lib/ruby_memcheck.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "nokogiri"
+require "rake/testtask"
+
+require "ruby_memcheck/configuration"
+require "ruby_memcheck/frame"
+require "ruby_memcheck/stack"
+require "ruby_memcheck/test_task"
+require "ruby_memcheck/valgrind_error"
+require "ruby_memcheck/version"
+
+module RubyMemcheck
+  class << self
+    def config(**opts)
+      @default_configuration = Configuration.new(**opts)
+    end
+
+    def default_configuration
+      unless @default_configuration
+        raise "RubyMemcheck is not configured with a default configuration. "\
+          "Please run RubyMemcheck.config before using it."
+      end
+      @default_configuration
+    end
+  end
+end

data/ruby_memcheck.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/ruby_memcheck/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "ruby_memcheck"
+  spec.version       = RubyMemcheck::VERSION
+  spec.authors       = ["Peter Zhu"]
+  spec.email         = ["peter@peterzhu.ca"]
+
+  spec.summary       = "Use Valgrind memcheck without going crazy"
+  spec.homepage      = "https://github.com/peterzhu2118/ruby_memcheck"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("nokogiri")
+
+  spec.add_development_dependency("minitest", "~> 5.0")
+  spec.add_development_dependency("rake", "~> 13.0")
+  spec.add_development_dependency("rake-compiler", "~> 1.1")
+  spec.add_development_dependency("rubocop", "~> 1.22")
+  spec.add_development_dependency("rubocop-shopify", "~> 2.3")
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: ruby_memcheck
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Zhu
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-10-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.22'
+- !ruby/object:Gem::Dependency
+  name: rubocop-shopify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description:
+email:
+- peter@peterzhu.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/lint.yml"
+- ".github/workflows/test.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby_memcheck.rb
+- lib/ruby_memcheck/configuration.rb
+- lib/ruby_memcheck/frame.rb
+- lib/ruby_memcheck/stack.rb
+- lib/ruby_memcheck/test_task.rb
+- lib/ruby_memcheck/valgrind_error.rb
+- lib/ruby_memcheck/version.rb
+- ruby_memcheck.gemspec
+homepage: https://github.com/peterzhu2118/ruby_memcheck
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/peterzhu2118/ruby_memcheck
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: Use Valgrind memcheck without going crazy
+test_files: []