ruby_memcheck 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 149d43766feab55baa7f6822767ec4d68ae465668fc6183c8ad9cca7b4bd7955
-  data.tar.gz: 1d97e5ac70355a3b14f14e7e7acbba925b8d4e43a1907e5ceb0af7de29a60732
+  metadata.gz: 751718a23aee213973e93656dba653e4e253fd3f83618007c39e809827273ac5
+  data.tar.gz: 55d6196fb48e0c18fabb5c87536c2c4114d7a1c1a2b04128ec2c707389934de0
 SHA512:
-  metadata.gz: f1953d6feaba3701b695d0c8d84086efa586ce05e2da518b4e68e8e8b5f8a615e35360ce36a32e5f61a489bc3bb88517b48353a644a72cb2f902edb6ff34e633
-  data.tar.gz: a95a1a75f17ddafb64a2e767d0a32ce5aa0b941e5bd4522a9ab5b3bbe5fc647c49579014fe09571f27b64e543521d6327b3dbde4e066044005696edc13442a39
+  metadata.gz: 861d0639b3d06d124f4020cb372472954018ad113ba4864b9367be6c6d167a338297d18c7c4adbcae767ba4a30e8925402bd7faa5a97841a513914ce41e10997
+  data.tar.gz: e0dc1e236947746baef93281f00ec8129f651b7e560e56d2dffc5c188f14e5b32b39adc204ecea2da51c1e9ed341f1c00ff55b4b82521bb2b7b54085d5bfddfc

data/README.md

@@ -10,10 +10,13 @@ This gem provides a sane way to use Valgrind's memcheck on your native extension
     1. [Limitations](#limitations)
 1. [Installation](#installation)
 1. [Setup](#setup)
+1. [Configuration](#configuration)
+1. [Suppression files](#suppression-files)
+1. [License](#license)
 
 ## 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.
+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?
 
@@ -21,11 +24,11 @@ Only gems with native extensions can use this gem. If your gem is written in pla
 
 ### 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.
+This gem runs Valgrind with the `--xml` option to generate an 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.
+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.
@@ -115,7 +118,47 @@ The easiest way to use this gem is to use it on your test suite (minitest or RSp
       ```
 
 1. You're ready to run your test suite with Valgrind using `rake test:valgrind` or `rake spec:valgrind`! Note that this will take a while to run because Valgrind will make Ruby significantly slower.
-1. (Optional) If you find false-positives in the output, you can create suppression files in a `suppressions` directory in the root directory of your gem. In this directory, you can create [Valgrind suppression files](https://wiki.wxwidgets.org/Valgrind_Suppression_File_Howto). The most basic suppression file is `your_binary_name_ruby.supp`. If you want some suppressions for only specific versions of Ruby, you can add the Ruby version to the filename. For example, `your_binary_name_ruby-3.supp` will suppress for any Rubies with a major version of 3 (e.g. 3.0.0, 3.1.1, etc.), while suppression file `your_binary_name_ruby-3.1.supp` will only be used for Ruby with a major and minor version of 3.1 (e.g. 3.1.0, 3.1.1, etc.).
+1. (Optional) If you find false positives in the output, you can create Valgrind suppression files. See the [`Suppression files`](#suppression-files) section for more details.
+
+## Configuration
+
+When you run `RubyMemcheck.config`, you are creating a default `RubyMemcheck::Configuration`. By default, the Rake tasks for minitest and RSpec will use this configuration. You can also manually pass in a `Configuration` object as the first argument to the constructor of `RubyMemcheck::TestTask` or `RubyMemcheck::RSpec::RakeTask` to use a different `Configuration` object rather than the default one.
+
+`RubyMemcheck::Configuration` accepts a variety of keyword arguments. Here are all the arguments:
+
+- `binary_name`: Required. The binary name of your native extension gem. This is the same value you passed into `create_makefile` in your `extconf.rb` file.
+- `ruby`: Optional. The command to run to invoke Ruby. Defaults to the Ruby that is currently being used.
+- `valgrind`: Optional. The command to run to invoke Valgrind. Defaults to the string `"valgrind"`.
+- `valgrind_options`: Optional. Array of options to pass into Valgrind. This is only present as an escape hatch, so avoid using it. This may be deprecated or removed in future versions.
+- `valgrind_suppressions_dir`: Optional. The string path of the directory that stores suppression files for Valgrind. See the [`Suppression files`](#suppression-files) section for more details. Defaults to `suppressions`.
+- `valgrind_generate_suppressions`: Optional. Whether suppressions should also be outputted along with the errors. the [`Suppression files`](#suppression-files) section for more details. Defaults to `false`.
+- `skipped_ruby_functions`: Optional. Ruby functions that are ignored because they are considered a call back into Ruby. This is only present as an escape hatch, so avoid using it. If you find another Ruby function that is a false positive because it calls back into Ruby, please send a patch into this repo. Otherwise, use a Valgrind suppression file.
+- `valgrind_xml_dir`: Optional. The directory to store temporary XML files for Valgrind. It defaults to a temporary directory. This is present for development debugging, so you shouldn't have to use it.
+- `output_io`: Optional. The `IO` object to output Valgrind errors to. Defaults to standard error.
+
+## Suppression files
+
+If you find false positives in the output, you can create suppression files in a `suppressions` directory in the root directory of your gem. In this directory, you can create [Valgrind suppression files](https://wiki.wxwidgets.org/Valgrind_Suppression_File_Howto).
+
+The most basic suppression file is `your_binary_name_ruby.supp`. If you want some suppressions for only specific versions of Ruby, you can add the Ruby version to the filename. For example, `your_binary_name_ruby-3.supp` will suppress for any Rubies with a major version of 3 (e.g. 3.0.0, 3.1.1, etc.), while suppression file `your_binary_name_ruby-3.1.supp` will only be used for Ruby with a major and minor version of 3.1 (e.g. 3.1.0, 3.1.1, etc.).
+
+## Success stories
+
+Let's celebrate wins from this gem! If this gem was useful for you, please share your story below too!
+
+- [`liquid-c`](https://github.com/Shopify/liquid-c):
+  - Found 2 memory leaks: [#157](https://github.com/Shopify/liquid-c/pull/157), [#161](https://github.com/Shopify/liquid-c/pull/161)
+  - Running on CI: [#162](https://github.com/Shopify/liquid-c/pull/162)
+- [`nokogiri`](https://github.com/sparklemotion/nokogiri):
+  - Found 5 memory leaks: [4 in #2345](https://github.com/sparklemotion/nokogiri/pull/2345), [#2347](https://github.com/sparklemotion/nokogiri/pull/2347)
+  - CI is WIP: [#2344](https://github.com/sparklemotion/nokogiri/pull/2344)
+- [`rotoscope`](https://github.com/Shopify/rotoscope):
+  - Found a [memory leak in Ruby TracePoint](https://bugs.ruby-lang.org/issues/18264)
+  - Running on CI: [#89](https://github.com/Shopify/rotoscope/pull/89)
+- [`protobuf`](https://github.com/protocolbuffers/protobuf):
+  - Found 1 memory leak: [#9150](https://github.com/protocolbuffers/protobuf/pull/9150)
+- [`gRPC`](https://github.com/grpc/grpc):
+  - Found 1 memory leak: [#27900](https://github.com/grpc/grpc/pull/27900)
 
 ## License
 

data/lib/ruby_memcheck/configuration.rb

@@ -16,7 +16,7 @@ module RubyMemcheck
       /\Aeval_string_with_cref\z/,
       /\Arb_add_method_cfunc\z/,
       /\Arb_check_funcall/,
-      /\Arb_class_boot\z/,
+      /\Arb_class_boot\z/, # Called for all the different ways to create a Class
       /\Arb_enc_raise\z/,
       /\Arb_exc_raise\z/,
       /\Arb_extend_object\z/,
@@ -27,6 +27,7 @@ module RubyMemcheck
       /\Arb_raise\z/,
       /\Arb_rescue/,
       /\Arb_respond_to\z/,
+      /\Arb_thread_create\z/, # Threads are relased to a cache, so they may be reported as a leak
       /\Arb_yield/,
     ].freeze
 
@@ -79,42 +80,6 @@ module RubyMemcheck
       ].flatten.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 ||
-        # Hack to fix Ruby built with --enabled-shared
-        File.basename(frame.obj) == "libruby.so.#{RUBY_VERSION}"
-    end
-
-    def frame_in_binary?(frame)
-      if frame.obj
-        File.basename(frame.obj, ".*") == binary_name
-      else
-        false
-      end
-    end
-
     private
 
     def get_valgrind_suppression_files(dir)

data/lib/ruby_memcheck/frame.rb

@@ -2,17 +2,29 @@
 
 module RubyMemcheck
   class Frame
-    attr_reader :fn, :obj, :file, :line, :in_binary
-    alias_method :in_binary?, :in_binary
+    attr_reader :configuration, :fn, :obj, :file, :line
 
     def initialize(configuration, frame_xml)
+      @configuration = configuration
       @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
+    end
+
+    def in_ruby?
+      obj == configuration.ruby ||
+        # Hack to fix Ruby built with --enabled-shared
+        File.basename(obj) == "libruby.so.#{RUBY_VERSION}"
+    end
 
-      @in_binary = configuration.frame_in_binary?(self)
+    def in_binary?
+      if obj
+        File.basename(obj, ".*") == configuration.binary_name
+      else
+        false
+      end
     end
 
     def to_s

data/lib/ruby_memcheck/stack.rb

@@ -2,10 +2,38 @@
 
 module RubyMemcheck
   class Stack
-    attr_reader :frames
+    attr_reader :configuration, :frames
 
     def initialize(configuration, stack_xml)
+      @configuration = configuration
       @frames = stack_xml.xpath("frame").map { |frame| Frame.new(configuration, frame) }
     end
+
+    def skip?
+      in_binary = false
+
+      frames.each do |frame|
+        fn = frame.fn
+
+        if frame.in_ruby?
+          # If a stack from from the binary was encountered first, then this
+          # memory leak did not occur from Ruby
+          unless in_binary
+            # Skip this stack because it was called from Ruby
+            return true if configuration.skipped_ruby_functions.any? { |r| r.match?(fn) }
+          end
+        elsif frame.in_binary?
+          in_binary = true
+
+          # Skip the Init function because it is only ever called once, so
+          # leaks in it cannot cause memory bloat
+          return true if fn == "Init_#{configuration.binary_name}"
+        end
+      end
+
+      # Skip if the stack was never in the binary because it is very likely
+      # not a leak in the native gem
+      !in_binary
+    end
   end
 end

data/lib/ruby_memcheck/valgrind_error.rb

@@ -27,11 +27,7 @@ module RubyMemcheck
     end
 
     def skip?
-      if should_filter?
-        @configuration.skip_stack?(stack)
-      else
-        false
-      end
+      should_filter? && stack.skip?
     end
 
     def to_s

data/lib/ruby_memcheck/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_memcheck
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Peter Zhu
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-01 00:00:00.000000000 Z
+date: 2021-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri