allocation_stats 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce3ad497b9d8343b112d199d186f508a22e68515
+  data.tar.gz: 1f323cfd6854e10f26b66eb8f592cb8b577a88a7
+SHA512:
+  metadata.gz: 55b43fd195b3540b872af0c05e5a4b10d3f94fce8678dc00b7b7325d6eebb7b12e688caf858a8f9424d2e6bcc98347385a4807e840c3c95fc4759f501dfde9ec
+  data.tar.gz: 946cd053f108b4f6548b5991fa37d620cf2d5ae3df176a4a5cd8c9ec0a4a52ca6036f8abd67e28f3868dbf36ac6dd658c018ace0d1da761814ed1cbbde35aa4e

data/.gitignore

@@ -0,0 +1,2 @@
+doc
+.yardoc

data/.yardopts

@@ -0,0 +1 @@
+-m markdown - README.markdown LICENSE

data/Gemfile

@@ -0,0 +1,15 @@
+# Copyright 2013 Google Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0, found in the LICENSE file.
+
+source "https://rubygems.org"
+
+group :development do
+  gem "yard"
+end
+
+group :test do
+  gem "rspec"
+  gem "pry"
+
+  gem "yajl-ruby", "= 1.1.0"
+end

data/Gemfile.lock

@@ -0,0 +1,30 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.0.9)
+    diff-lcs (1.2.4)
+    method_source (0.8.2)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    slop (3.4.6)
+    yajl-ruby (1.1.0)
+    yard (0.8.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  rspec
+  yajl-ruby (= 1.1.0)
+  yard

data/LICENSE

@@ -0,0 +1,196 @@
+# @markup rdoc
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "{}" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+

data/README.markdown

@@ -0,0 +1,377 @@
+Introduction
+============
+
+AllocationStats is a rubygem that makes use of Ruby 2.1's new abilities to trace
+Ruby object allocations (MRI only). Ruby 2.1's new
+`ObjectSpace.trace_object_allocations` methods give only raw information, and
+are not immediately useful for anything beyond micro profiling. The data must be
+aggregated!
+
+AllocationStats collects all of the allocation information generated by
+`ObjectSpace.trace_object_allocations`, then provides mechanisms for filtering,
+grouping, and sorting the allocation information.
+
+Tabular Output examples
+-----------------------
+
+It is very easy to get some simple statistics out of AllocationStats.
+Wrap some code with `AllocationStats.trace` and print out a listing of all of the
+new object allocation information.
+
+As an example, lets look at `examples/my_class.rb`:
+
+```ruby
+class MyClass
+  def my_method
+    @hash = {1 => "foo", 2 => "bar"}
+  end
+end
+```
+
+And use that class in a bit of ad-hoc Ruby:
+
+```
+$ ruby -r ./lib/allocation_stats -r ./allocation
+stats = AllocationStats.trace { MyClass.new.my_method }
+puts stats.allocations(alias_paths: true).to_text
+^D
+    sourcefile       sourceline  class_path  method_id  memsize   class
+-------------------  ----------  ----------  ---------  -------  -------
+<PWD>/allocation.rb           4  MyClass     my_method        0  String
+<PWD>/allocation.rb           3  MyClass     my_method      192  Hash
+<PWD>/allocation.rb           3  MyClass     my_method        0  String
+<PWD>/allocation.rb           3  MyClass     my_method        0  String
+<PWD>/allocation.rb           3  MyClass     my_method        0  String
+-                             1  Class       new              0  MyClass
+```
+
+(I've used `alias_paths: true` above for readability. This way, the `sourcefile`
+column is not crazy long, using the full file path on my filesystem.)
+
+(This full example is found in `examples/trace_my_class_raw.rb`)
+
+We can also group allocations by one or more attributes, and get an aggregate
+count. Below, we group allocations by source file, source line, and class:
+
+```
+$ ruby -r ./lib/allocation_stats -r ./allocation
+stats = AllocationStats.trace { MyClass.new.my_method }
+puts stats.allocations(alias_paths: true).group_by(:sourcefile, :sourceline, :class).to_text
+^D
+    sourcefile       sourceline   class   count
+-------------------  ----------  -------  -----
+<PWD>/allocation.rb           4  String       1
+<PWD>/allocation.rb           3  Hash         1
+<PWD>/allocation.rb           3  String       3
+-                             1  MyClass      1
+```
+
+(This full example is found in `examples/trace_my_class_group_by.rb`)
+
+
+More on `trace_object_allocations()`
+---------------------------------------------
+
+To start at the beginning: Ruby 2.1 will be released with a new feature that
+enables one to trace object allocations. Through
+`ObjectSpace.trace_object_allocations`, one can trace the following properties
+for any new object allocation:
+
+* source file
+* source line
+* class path
+* method ID
+* generation
+
+Let's see this in action:
+
+```
+$ cat examples/trace_object_allocations.rb
+require 'objspace'
+
+ObjectSpace.trace_object_allocations do
+  a = [2,3,5,7,11,13,17,19,23,29,31]
+  puts ObjectSpace.allocation_sourcefile(a)
+  puts ObjectSpace.allocation_sourceline(a)
+end
+$ ruby ./examples/trace_object_allocations.rb
+allocations.rb
+4
+```
+
+Example from the specs
+----------------------
+
+```ruby
+existing_array = [1,2,3,4,5]
+
+stats = AllocationStats.trace do
+  new_string     = "stringy string"
+  another_string = "another string"
+  an_array       = [1,1,2,3,5,8,13,21,34,55]
+  a_foreign_string = allocate_a_string_from_spec_helper
+end
+
+results = stats.allocations.group_by(:@sourcefile, :class).to_a
+```
+
+We've grouped all of the traced allocations by the **source file** that the
+allocation occurred in, and the **class of the object** that was allocated. The
+list of allocations can be "transformed" in a number of ways (including
+the above `#group_by`), so the transformations must be ultimately resolved by calling
+`#to_a` (similar to ActiveRecord relations).  The result is the following Hash of (sourcefile, class) tuple keys and
+AllocationStats::Allocation values:
+
+```ruby
+{
+  [".../spec/spec_helper.rb", String]
+    =>
+  [#<AllocationStats::Allocation:0x007f132ac3f160
+    @object="a string from spec_helper",
+    @memsize=0,
+    @sourcefile=".../spec/spec_helper.rb",
+    @sourceline=14,
+    @class_path="Object",
+    @method_id=:allocate_a_string_from_spec_helper>
+  ],
+
+  [".../spec/allocation_stats_spec.rb", Array]
+    =>
+  [#<AllocationStats::Allocation:0x007f132ac3e968
+    @object=[1, 1, 2, 3, 5, 8, 13, 21, 34, 55],
+    @memsize=80,
+    @sourcefile=".../spec/allocation_stats_spec.rb",
+    @sourceline=78,
+    @class_path=nil,
+    @method_id=nil>
+  ],
+
+  [".../spec/allocation_stats_spec.rb", String]
+    =>
+  [ #<AllocationStats::Allocation:0x007f132ac3e0d0
+      @object="another string",
+      @memsize=0,
+      @sourcefile=".../spec/allocation_stats_spec.rb",
+      @sourceline=77,
+      @class_path=nil,
+      @method_id=nil>,
+    #<AllocationStats::Allocation:0x007f132ac3d838
+      @object="stringy string",
+      @memsize=0,
+      @sourcefile=".../spec/allocation_stats_spec.rb",
+      @sourceline=76,
+      @class_path=nil,
+      @method_id=nil>
+  ]
+}
+```
+
+(I've manually inserted the ellipses.)
+
+You can see that there are three different groups:
+
+* `[spec_helper.rb, String]`
+* `[allocation_stats_spec.rb, Array]`
+* `[object_space_stats.rb, String]`
+
+Only one allocation belongs to each of the first two groups, and two allocations
+make up the second group.
+
+A little slower
+---------------
+
+Let's look at this example a little slower. Firstly, let's look at how we
+collect object allocations using AllocationStats:
+
+```ruby
+stats = AllocationStats.trace do
+  new_string     = "stringy string"
+  another_string = "another string"
+  an_array       = [1,1,2,3,5,8,13,21,34,55]
+  a_foreign_string = allocate_a_string_from_spec_helper
+end
+```
+
+Stats are collected by running a block through `AllocationStats.trace`. This is
+largely just a thin wrapper around `trace_object_allocations()`. You are handed
+back your new AllocationStats, which essentially just holds all of the
+allocation information, accessible via `#allocations`. Let's look at the next
+line to see how we can pull useful information out:
+
+```ruby
+  results = stats.allocations.group_by(:@sourcefile, :class).to_a
+```
+
+If you are used to chaining ActiveRecord relations, some of this might look
+familiar to you: `stats.allocations` will hand you back an {AllocationsProxy}
+object, designed to hold the various transformations that you wish to run the
+allocations through.  AllocationsProxy uses the Command pattern to store up
+transformations before they will actually be applied. In this example, we only
+make one transformation: `group_by(:@sourcefile, :class)`.  This method just
+returns the same AllocationsProxy object back, so that transformations can be
+chained. The final call that will execute the transformations is `#to_a`
+(aliased to `#all`, just like ActiveRecord).
+
+Psych Example
+-------------
+
+Let's look at an example with more varied allocations, using Ruby's Psych. This
+one is found in `examples/trace_psych_keys.rb`:
+
+```ruby
+stats = AllocationStats.trace do
+  y = YAML.dump(["one string", "two string"]) # lots of objects from Rbconfig::CONFIG["rubylibdir"]
+end
+
+stats.allocations.group_by(:sourcefile, :class).all.keys.each { |key| puts key.inspect }
+
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Array]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", MatchData]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Method]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/nodes/node.rb", Array]
+["(eval)", Psych::Nodes::Sequence]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/tree_builder.rb", Psych::Nodes::Document]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/tree_builder.rb", Psych::Nodes::Stream]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Proc]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", RubyVM::Env]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Hash]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Psych::Visitors::YAMLTree::Registrar]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Psych::Visitors::YAMLTree]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/scalar_scanner.rb", Hash]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Psych::ScalarScanner]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/class_loader.rb", Hash]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Psych::ClassLoader]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/tree_builder.rb", Array]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/yaml_tree.rb", Psych::TreeBuilder]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych.rb", Hash]
+["examples/trace_psych_inspect.rb", Array]
+["examples/trace_psych_inspect.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/emitter.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/emitter.rb", Array]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/emitter.rb", RubyVM::InstructionSequence]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/visitor.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/visitor.rb", MatchData]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/visitor.rb", Regexp]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/visitors/emitter.rb", Psych::Emitter]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/nodes/node.rb", Psych::Visitors::Emitter]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/nodes/node.rb", StringIO]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/nodes/node.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/tree_builder.rb", Psych::Nodes::Scalar]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/scalar_scanner.rb", String]
+["/usr/local/rbenv/versions/2.1.0-dev/lib/ruby/2.1.0/psych/scalar_scanner.rb", MatchData]
+```
+
+Again, it is difficult to find useful information from these results without
+aggregating. Let's do that (`examples/trace_psych_group_by`):
+
+```ruby
+stats = AllocationStats.trace do
+  y = YAML.dump(["one string", "two string"]) # lots of objects from Rbconfig::CONFIG["rubylibdir"]
+end
+
+puts stats.allocations(alias_paths: true).group_by(:sourcefile, :class).to_text
+
+               sourcefile                                class                  count
+----------------------------------------  ------------------------------------  -----
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Array                                    12
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  String                                   20
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  MatchData                                 3
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Method                                    5
+<RUBYLIBDIR>/psych/nodes/node.rb          Array                                     3
+(eval)                                    Psych::Nodes::Sequence                    1
+<RUBYLIBDIR>/psych/tree_builder.rb        Psych::Nodes::Document                    1
+<RUBYLIBDIR>/psych/tree_builder.rb        Psych::Nodes::Stream                      1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Proc                                      1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  RubyVM::Env                               1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Hash                                      3
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Psych::Visitors::YAMLTree::Registrar      1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Psych::Visitors::YAMLTree                 1
+<RUBYLIBDIR>/psych/scalar_scanner.rb      Hash                                      2
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Psych::ScalarScanner                      1
+<RUBYLIBDIR>/psych/class_loader.rb        Hash                                      1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Psych::ClassLoader                        1
+<RUBYLIBDIR>/psych/tree_builder.rb        Array                                     1
+<RUBYLIBDIR>/psych/visitors/yaml_tree.rb  Psych::TreeBuilder                        1
+<RUBYLIBDIR>/psych.rb                     Hash                                      1
+./examples/trace_psych_raw.rb             Array                                     1
+./examples/trace_psych_raw.rb             String                                    2
+<RUBYLIBDIR>/psych/visitors/emitter.rb    String                                   29
+<RUBYLIBDIR>/psych/visitors/emitter.rb    Array                                     3
+<RUBYLIBDIR>/psych/visitors/emitter.rb    RubyVM::InstructionSequence               1
+<RUBYLIBDIR>/psych/visitors/visitor.rb    String                                   38
+<RUBYLIBDIR>/psych/visitors/visitor.rb    MatchData                                 5
+<RUBYLIBDIR>/psych/visitors/visitor.rb    Regexp                                    1
+<RUBYLIBDIR>/psych/visitors/emitter.rb    Psych::Emitter                            1
+<RUBYLIBDIR>/psych/nodes/node.rb          Psych::Visitors::Emitter                  1
+<RUBYLIBDIR>/psych/nodes/node.rb          StringIO                                  1
+<RUBYLIBDIR>/psych/nodes/node.rb          String                                    3
+<RUBYLIBDIR>/psych/tree_builder.rb        Psych::Nodes::Scalar                      2
+<RUBYLIBDIR>/psych/scalar_scanner.rb      String                                    5
+<RUBYLIBDIR>/psych/scalar_scanner.rb      MatchData                                 2
+```
+
+Burn One
+========
+
+If you find a lot of allocations in `kernel_require.rb` or a lot of allocations
+of `RubyVM::InstructuinSequences`, you can "burn" one or more calls to your
+block with the `burn` keyword. For example:
+`AllocationStats.new(burn: 3).trace{ ... }` will first call the block 3 times,
+without tracing allocations, before calling the block a 4th time, tracing
+allocations.
+
+The API
+=======
+
+So what methods are available on that AllocationsProxy thing? So far, the API
+consists of:
+
+* `#group_by`
+* `#from` takes one String argument, which will matched against the
+  allocation filename.
+* `#not_from` is the opposite of `#from`.
+* `#from_pwd` will filter the allocations down to those originating from `pwd`
+  (e.g. allocations originating from "my project")
+* `#where` accepts a hash of faux attribute keys. For example,
+
+  ```ruby
+  allocations.where(class: String)
+  ```
+
+  It does not yet accept lambdas as values, which _would_ enable
+  ActiveRecord-4-like calls, like
+
+  ```ruby
+  allocations.where(class: Array, size: ->(size) { size > 10 }
+  ```
+* `#bytes`, which has an inconsistent definition, I think... TODO
+
+What are faux attributes?
+-------------------------
+
+Valid values for `#group_by` and `#where` include:
+* instance variables on each `Allocation`. These include `:sourcefile`,
+  `:sourceline`, etc.
+* methods available on the objects that were allocated. These include things
+  like `:class`, or even `:size` if you know you only have objects that respond
+  to `:size`.
+* Allocation helper methods that return something special about the allocated
+  object. Right now this just includes `:class_plus`.
+
+I'm calling these things that you can group by or filter by, "faux attributes."
+
+What is `class_plus`?
+---------------------
+
+References
+==========
+
+This new feature was inspired by work that @tmm1 did at GitHub, as
+described in
+[this post](https://github.com/blog/1489-hey-judy-don-t-make-it-bad). It was
+proposed as a feature in Ruby Core by @tmm1 in
+[Ruby issue #8107](http://bugs.ruby-lang.org/issues/8107), and @ko1 wrote it
+into MRI. He introduces the feature in his Ruby Kaigi 2013 presentation, on
+slides 29 through 33
+[[pdf](http://www.atdot.net/~ko1/activities/RubyKaigi2013-ko1.pdf)].