mem_inspect 1.0.0

data/Manifest.txt

@@ -0,0 +1,10 @@
+Manifest.txt
+README
+Rakefile
+bin/ruby_mem_dump
+bin/ruby_mem_inspect_build
+gc.c.patch
+lib/mem_inspect.rb
+lib/mem_inspect/aquaterm_viewer.rb
+lib/mem_inspect/png_viewer.rb
+lib/mem_inspect/viewer.rb

data/README

@@ -0,0 +1,60 @@
+= mem_inspect
+
+== About
+
+mem_inspect is ObjectSpace.each_object on crack.  mem_inspect gives you the
+contents of each slot in Ruby's heap.  mem_inspect also includes viewers that
+let you visualize the contents of Ruby's heap.
+
+== Installing mem_inspect
+
+First, install the gem:
+
+  $ sudo gem install mem_inspect
+
+Then you need to build a patched ruby:
+
+  ruby_mem_inspect_build
+
+Optionally, you can install the patch ruby binary.  It will be named
+"ruby_mem_inspect".
+
+== Using mem_inspect
+
+=== Dumping a PNG
+
+To get a PNG of memory use:
+
+  mem_inspect_ruby_1_8/ruby_mem_inspect -S ruby_mem_dump
+
+To get a PNG of memory use in your application:
+
+  require 'mem_inspect'
+  require 'mem_inspect/png_viewer'
+
+And when you want to dump a PNG:
+  
+  MemInspect::PNGViewer.new(1024, 768).draw
+
+== Dumping via AquaTerm
+
+First you'll need to install RubyCocoa.  You can find instructions for that
+here:
+
+http://rubycocoa.sourceforge.net/doc/getting.en.html
+
+http://rubycocoa.sourceforge.net/doc/build.en.html
+
+Then you'll need to download AquaTerm:
+
+http://sourceforge.net/project/showfiles.php?group_id=39915
+
+Once you have all that installed you can dump to an AquaTerm plot:
+
+  require 'mem_inspect'
+  require 'mem_inspect/aquaterm_viewer'
+
+And when you want a plot:
+
+  MemInspect::AquatermViewer.new(1024, 768).draw
+

data/Rakefile

@@ -0,0 +1,63 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+$VERBOSE = nil
+
+spec = Gem::Specification.new do |s|
+  s.name = 'mem_inspect'
+  s.version = '1.0.0'
+  s.summary = 'ObjectSpace.each_object on crack'
+  s.description = 'mem_inspect walks Ruby\'s heaps giving you the contents of
+each slot.  mem_inspect also includes viewers that will let you visualize
+the contents of Ruby\'s heap.'
+  s.author = 'Eric Hodel'
+  s.email = 'drbrain@segment7.net'
+
+  s.has_rdoc = true
+  s.files = File.read('Manifest.txt').split($/)
+  s.require_path = 'lib'
+
+  s.executables = %w[ruby_mem_dump ruby_mem_inspect_build]
+
+  s.add_dependency 'RubyInline', '>= 3.5.0'
+  s.add_dependency 'png', '>= 1.0.0'
+end
+
+desc 'Run tests'
+task :default => [ :test ]
+
+Rake::TestTask.new('test') do |t|
+  t.libs << 'test'
+  t.pattern = 'test/test_*.rb'
+  t.verbose = true
+end
+
+desc 'Update Manifest.txt'
+task :update_manifest do
+  sh "find . -type f | sed -e 's%./%%' | egrep -v 'svn|swp|~' | egrep -v '^(doc|pkg)/' | sort > Manifest.txt"
+end
+
+desc 'Generate RDoc'
+Rake::RDocTask.new :rdoc do |rd|
+  rd.rdoc_dir = 'doc'
+  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
+  rd.main = 'README'
+  rd.options << '-d' if `which dot` =~ /\/dot/
+  rd.options << '-t mem_inspect'
+end
+
+desc 'Build Gem'
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Clean up'
+task :clean => [ :clobber_rdoc, :clobber_package ]
+
+desc 'Clean up'
+task :clobber => [ :clean ]
+
+# vim: syntax=Ruby

data/bin/ruby_mem_dump

@@ -0,0 +1,8 @@
+#!/usr/local/bin/ruby -w
+
+require 'mem_inspect'
+require 'mem_inspect/png_viewer'
+
+mv = MemInspect::PNGViewer.new 1024, 768
+mv.draw
+

data/bin/ruby_mem_inspect_build

@@ -0,0 +1,45 @@
+#!/usr/local/bin/ruby -w
+
+require 'rubygems'
+require 'rake'
+
+ruby_dir = "mem_inspect_ruby_1_8"
+old_pwd = Dir.pwd
+
+if File.exist? ruby_dir then
+  Dir.chdir ruby_dir do "sh cvs up" end
+else
+  sh "cvs -z4 -d :pserver:anonymous@cvs.ruby-lang.org:/src co -d #{ruby_dir} -r ruby_1_8 ruby"
+end
+
+Dir.chdir ruby_dir do
+  sh "rm gc.c"
+  sh "cvs up gc.c"
+  sh "patch < #{File.join old_pwd, "gc.c.patch"}"
+  sh "autoconf" unless File.exist? "configure"
+  sh "./configure --program-suffix=_mem_inspect" unless File.exist? "Makefile"
+  sh "make"
+
+  puts "*" * 80
+  puts "Ruby has been built in #{ruby_dir}, but not installed"
+  puts
+  puts "If you run:"
+  puts
+  puts "\tcd #{ruby_dir}; sudo make install"
+  puts
+  puts "YOU WILL OVERWRITE YOUR STDLIB"
+  puts
+  puts "Generally, this is harmless, but you may not want that."
+  puts "So I'll let you do that all by yourself."
+  puts
+  puts "You may now run ruby_mem_dump using the patched ruby:"
+  puts
+  puts "\t#{File.join ruby_dir, "ruby_mem_inspect"} -S ruby_mem_dump"
+  puts
+  puts "If you haven't installed mem_inspect:"
+  puts
+  puts "\t#{File.join ruby_dir, "ruby_mem_inspect"} -Ilib bin/ruby_mem_dump"
+  puts
+  puts "*" * 80
+end
+

data/gc.c.patch

@@ -0,0 +1,30 @@
+Index: gc.c
+===================================================================
+RCS file: /src/ruby/gc.c,v
+retrieving revision 1.168.2.45
+diff -p -u -r1.168.2.45 gc.c
+--- gc.c        25 Aug 2006 08:12:46 -0000      1.168.2.45
++++ gc.c        31 Aug 2006 18:47:55 -0000
+@@ -323,6 +323,22 @@ static struct heaps_slot {
+ static int heaps_length = 0;
+ static int heaps_used   = 0;
+ 
++struct heaps_slot *
++rb_gc_heap_slots()
++{
++    return heaps;
++}
++
++int
++rb_gc_heaps_used() {
++    return heaps_used;
++}
++
++int
++rb_gc_heaps_length() {
++    return heaps_length;
++}
++
+ #define HEAP_MIN_SLOTS 10000
+ static int heap_slots = HEAP_MIN_SLOTS;
+ 

data/lib/mem_inspect.rb

@@ -0,0 +1,197 @@
+begin
+  require 'inline'
+rescue LoadError
+  require 'rubygems'
+  require 'inline'
+end
+
+##
+# ObjectSpace.each_object on crack.
+#
+# MemInspect allows you to walk Ruby's heaps and gives you the contents of
+# each heap slot.
+
+class MemInspect
+
+  inline do |builder|
+    builder.include '"node.h"' # struct RNode
+    builder.include '"st.h"'  # struct st_table
+    builder.include '"re.h"'  # struct RRegexp
+    builder.include '"env.h"' # various structs
+
+    builder.prefix <<-EOC
+      typedef struct RVALUE {
+          union {
+              struct {
+                  unsigned long flags; /* always 0 for freed obj */
+                  struct RVALUE *next;
+              } free;
+              struct RBasic  basic;
+              struct RObject object;
+              struct RClass  klass;
+              struct RFloat  flonum;
+              struct RString string;
+              struct RArray  array;
+              struct RRegexp regexp;
+              struct RHash   hash;
+              struct RData   data;
+              struct RStruct rstruct;
+              struct RBignum bignum;
+              struct RFile   file;
+              struct RNode   node;
+              struct RMatch  match;
+              struct RVarmap varmap;
+              struct SCOPE   scope;
+          } as;
+      } RVALUE;
+
+      struct heaps_slot {
+          void *membase;
+          RVALUE *slot;
+          int limit;
+      };
+
+      struct heaps_slot * rb_gc_heap_slots();
+      int rb_gc_heaps_used();
+      int rb_gc_heaps_length();
+    EOC
+
+    ##
+    # Number of struct heaps_slots used
+
+    builder.c <<-EOC
+      static int
+      heaps_used() {
+        return rb_gc_heaps_used();
+      }
+    EOC
+
+    ##
+    # Length of the struct heaps_slots allocated (I think)
+
+    builder.c <<-EOC
+      static int
+      heaps_length() {
+        return rb_gc_heaps_length();
+      }
+    EOC
+
+    # [Type flag, object size, object]
+
+    types = [
+      ['T_NONE',    0, 'unknown'],
+      ['T_NIL',     0, 'Qnil'],
+      ['T_OBJECT',  'sizeof(struct RObject) + sizeof(struct st_table)'],
+      ['T_CLASS',   'sizeof(struct RClass) + sizeof(struct st_table) * 2'],
+      ['T_ICLASS',  'sizeof(struct RClass)', 'iclass'],
+      ['T_MODULE',  'sizeof(struct RObject) + sizeof(struct st_table) * 2'],
+      ['T_FLOAT',   'sizeof(struct RFloat)'],
+      ['T_STRING',
+       'sizeof(struct RString) + (FL_TEST(RSTRING(p), ELTS_SHARED) ? 0 : RSTRING(p)->len)'],
+      ['T_REGEXP',  'sizeof(struct RRegexp) + RREGEXP(p)->len'],
+      ['T_ARRAY',
+       'sizeof(struct RArray) + (FL_TEST(RARRAY(p), ELTS_SHARED) ? 0 : RARRAY(p)->len * 4)'],
+      ['T_FIXNUM',  0],
+      ['T_HASH',    'sizeof(struct RHash) + sizeof(struct st_table)'],
+      ['T_STRUCT',  'sizeof(struct RStruct) + RSTRUCT(p)->len'],
+      ['T_BIGNUM',  'sizeof(struct RBignum) + RBIGNUM(p)->len'],
+      ['T_FILE',    'sizeof(struct RFile)'],
+
+      ['T_TRUE',    0, 'Qtrue'],
+      ['T_FALSE',   0, 'Qfalse'],
+      ['T_DATA',    'sizeof(struct RData)'],
+      ['T_MATCH',   'sizeof(struct RMatch)'],
+      ['T_SYMBOL',  0],
+
+      ['T_BLKTAG',  0, 'unknown'],
+      ['T_UNDEF',   0, 'unknown'],
+      ['T_VARMAP',  'sizeof(struct RVarmap)', 'varmap'], # TODO linked-list
+      ['T_SCOPE',
+       'sizeof(struct SCOPE) +
+        (((struct SCOPE *)p)->local_tbl ? ((struct SCOPE *)p)->local_tbl[0] : 0)',
+       'scope'],
+      ['T_NODE', 'sizeof(struct RNode)', 'node'], # TODO SCOPE and ALLOCA nodes
+    ]
+
+    types.each do |type|
+      type[2] = '(VALUE)p' if type[2].nil?
+    end
+
+    ##
+    # Generates the cases for the switch statement
+
+    def self.make_switch(types)
+      types.map do |type, size, object|
+        ["case #{type}:",
+         "  size = #{size};",
+         "  obj = #{object};",
+         "  break;",
+         nil]
+      end.join("\n")
+    end
+
+    ##
+    # Walks the heap slots yielding each item's address, size and value.
+    #
+    # The value may be:
+    # :__free:: Unassigned heap slot
+    # Object:: Ruby object
+    # :__node:: Ruby AST node
+    # :__iclass:: module instance (created via include)
+    # :__scope:: ruby interpreter scope
+    # :__varmap:: variable map (see eval.c, parse.y)
+    # :__unknown:: unknown item
+    #
+    # The size of objects may not be correct.  Please fix if you find an
+    # error.
+
+    builder.c <<-EOC
+      static void
+      walk() {
+        RVALUE *p, *pend;
+        VALUE ary = rb_ary_new2(3);
+        VALUE unknown = ID2SYM(rb_intern("__unknown"));
+        VALUE iclass = ID2SYM(rb_intern("__iclass"));
+        VALUE varmap = ID2SYM(rb_intern("__varmap"));
+        VALUE scope = ID2SYM(rb_intern("__scope"));
+        VALUE node = ID2SYM(rb_intern("__node"));
+        VALUE free = ID2SYM(rb_intern("__free"));
+        VALUE obj = unknown;
+        long size = 0;
+        struct heaps_slot * heaps = rb_gc_heap_slots();
+        int i;
+
+        for (i = 0; i < rb_gc_heaps_used(); i++) {
+          p = heaps[i].slot;
+          pend = p + heaps[i].limit;
+          for (; p < pend; p++) {
+            size = 0;
+            obj = free;
+            if (p->as.basic.flags) { /* always 0 for freed objects */
+              switch (TYPE(p)) {
+                #{make_switch types}
+
+                default:
+                  if (!p->as.basic.klass) {
+                    obj = unknown;
+                  } else {
+                    obj = (VALUE)p;
+                  }
+              }
+
+              if (FL_TEST(obj, FL_EXIVAR))
+                size += sizeof(struct st_table);
+            }
+            rb_ary_store(ary, 0, LONG2NUM((long)p));
+            rb_ary_store(ary, 1, INT2FIX(size));
+            rb_ary_store(ary, 2, obj);
+
+            rb_yield(ary);
+          }
+        }
+      }
+    EOC
+  end
+
+end
+

data/lib/mem_inspect/aquaterm_viewer.rb

@@ -0,0 +1,84 @@
+require 'osx/cocoa'
+require 'mem_inspect'
+require 'mem_inspect/viewer'
+
+##
+# Prints plots of memory to an AquaTerm window.
+#
+# Requires RubyCocoa and the AquaTerm framework.
+
+class MemInspect::AquatermViewer < MemInspect::Viewer
+  OSX::NSBundle.bundleWithPath(File.expand_path("/Library/Frameworks/Aquaterm.framework")).load
+  OSX.ns_import :AQTAdapter
+
+  BLACK = 0 # unalloc
+  WHITE = 1
+  RED = 2
+  GREEN = 3
+  GRAY = 4 # free
+
+  ##
+  # Creates a new AquatermViewer.
+
+  def initialize(width, height)
+    super
+
+    @adapter = OSX::AQTAdapter.alloc.init
+    @adapter.openPlotWithIndex 1
+    @adapter.setPlotSize [@width, @height]
+    @adapter.setPlotTitle 'Memory Map'
+
+    @adapter.setColormapEntry_red_green_blue 0, 0.0, 0.0, 0.0 # black
+    @adapter.setColormapEntry_red_green_blue 1, 1.0, 1.0, 1.0 # white
+    @adapter.setColormapEntry_red_green_blue 2, 1.0, 0.0, 0.0 # red
+    @adapter.setColormapEntry_red_green_blue 3, 0.0, 1.0, 0.0 # green
+    @adapter.setColormapEntry_red_green_blue 4, 0.7, 0.7, 0.7 # gray
+  end
+
+  ##
+  # Draws a plot and renders it in the active plot window.
+
+  def draw
+    fill_background
+    color = BLACK
+    last_color = color
+    x = 0
+    y = 0
+
+    @mem_inspect.walk do |address, size, object|
+      x, y = coords_for address
+
+      color = case object
+              when :__free then GRAY
+              when :__node then RED
+              when :__varmap, :__scope, :__unknown then WHITE
+              else GREEN
+              end
+
+      @adapter.takeColorFromColormapEntry color unless color == last_color
+      @adapter.moveToPoint [x, y] if x == 0
+      @adapter.addLineToPoint [x + 1, y + 1]
+      last_color = color
+    end
+
+  ensure # coords_for raises when out-of-bounds
+    @adapter.renderPlot
+  end
+
+  ##
+  # Fills the background of the plot, erasing the current contents.
+
+  def fill_background
+    @adapter.takeColorFromColormapEntry BLACK
+    @adapter.addFilledRect [0, 0, @width, @height] # background
+  end
+
+  ##
+  # Close the plot
+
+  def close
+    @adapter.closePlot
+  end
+
+end
+

data/lib/mem_inspect/png_viewer.rb

@@ -0,0 +1,47 @@
+begin
+  require 'png'
+rescue LoadError
+  require 'rubygems'
+  require 'png'
+end
+require 'mem_inspect'
+require 'mem_inspect/viewer'
+
+##
+# Prints plots of memory as a PNG.
+
+class MemInspect::PNGViewer < MemInspect::Viewer
+
+  ##
+  # Draws a PNG and saves it to memory_map.PID.timestamp.png
+
+  def draw
+    canvas = PNG::Canvas.new @width, @height, PNG::Color::Black
+    x = 0
+    y = 0
+    color = nil
+
+    @mem_inspect.walk do |address, size, object|
+      x, y = coords_for address
+
+      color = case object
+              when :__free    then PNG::Color::Gray
+              when :__node    then PNG::Color::Red
+              when :__scope   then PNG::Color::Yellow
+              when :__varmap  then PNG::Color::Purple
+              when :__unknown then PNG::Color::Orange
+              when :__iclass  then PNG::Color::White
+              else                 PNG::Color::Green
+              end
+
+      canvas[x, y] = color
+    end
+
+  ensure # coords_for raises when out-of-bounds
+    png = PNG.new canvas
+    file = "memory_map.#{$$}.#{Time.now.to_i}.png"
+    png.save file
+  end
+
+end
+

data/lib/mem_inspect/viewer.rb

@@ -0,0 +1,39 @@
+require 'mem_inspect'
+
+##
+# An abstract viewer class
+#
+# Use the PNGViewer as an example.
+
+class MemInspect::Viewer
+
+  ##
+  # Intializes the visualization.
+
+  def initialize(width, height)
+    @width = width
+    @height = height
+    @max = @width * @height
+
+    @mem_inspect = MemInspect.new
+  end
+
+  ##
+  # Returns x, y coordinates for +address+ based on the width and height of
+  # the visualization.
+
+  def coords_for(address)
+    index = address / 20
+
+    if index > @max then
+      raise "Ran out of plot space at index %d for 0x%x" % [index, address]
+    end
+
+    x = index % @width
+    y = index / @width
+
+    return x, y
+  end
+
+end
+

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.99
+specification_version: 1
+name: mem_inspect
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-08-31 00:00:00 -07:00
+summary: ObjectSpace.each_object on crack
+require_paths: 
+- lib
+email: drbrain@segment7.net
+homepage: 
+rubyforge_project: 
+description: mem_inspect walks Ruby's heaps giving you the contents of each slot.  mem_inspect also includes viewers that will let you visualize the contents of Ruby's heap.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Eric Hodel
+files: 
+- Manifest.txt
+- README
+- Rakefile
+- bin/ruby_mem_dump
+- bin/ruby_mem_inspect_build
+- gc.c.patch
+- lib/mem_inspect.rb
+- lib/mem_inspect/aquaterm_viewer.rb
+- lib/mem_inspect/png_viewer.rb
+- lib/mem_inspect/viewer.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- ruby_mem_dump
+- ruby_mem_inspect_build
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: RubyInline
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.5.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: png
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+    version: