bleak_house 3.7.1 → 4.0

data/CHANGELOG

@@ -1,4 +1,6 @@
 
+v4.0. Track spawn points live instead of sampling.
+
 v3.7.1. Fix some nil issues with corrupted dumps (cody caughlan).
 
 v3.7. Sample object contents. Restore Rails 1.2.x compatibility.

data/Manifest

@@ -1,77 +1,23 @@
 bin/bleak
 CHANGELOG
-ext/bleak_house/logger/build_logger.rb
-ext/bleak_house/logger/build_ruby.rb
-ext/bleak_house/logger/extconf.rb
-ext/bleak_house/logger/snapshot.c
-ext/bleak_house/logger/snapshot.h
-init.rb
-install.rb
-lib/bleak_house/analyzer/analyzer.rb
+ext/build_ruby.rb
+ext/build_snapshot.rb
+ext/extconf.rb
+ext/snapshot.c
+ext/snapshot.h
 lib/bleak_house/analyzer.rb
-lib/bleak_house/logger/source.rb
-lib/bleak_house/logger.rb
-lib/bleak_house/rails/action_controller.rb
-lib/bleak_house/rails/bleak_house.rb
-lib/bleak_house/rails/dispatcher.rb
-lib/bleak_house/rails.rb
-lib/bleak_house/support/core_extensions.rb
+lib/bleak_house/hook.rb
 lib/bleak_house.rb
 LICENSE
 LICENSE_BSD
 Manifest
 README
-ruby/gc.c.patch
-ruby/parse.y.patch
-ruby/ruby-1.8.6-p110.tar.bz2
-test/integration/app/app/controllers/application.rb
-test/integration/app/app/controllers/items_controller.rb
-test/integration/app/app/helpers/application_helper.rb
-test/integration/app/app/helpers/items_helper.rb
-test/integration/app/app/views/items/index.rhtml
-test/integration/app/config/boot.rb
-test/integration/app/config/database.yml
-test/integration/app/config/environment.rb
-test/integration/app/config/environments/development.rb
-test/integration/app/config/environments/production.rb
-test/integration/app/config/environments/test.rb
-test/integration/app/config/initializers/inflections.rb
-test/integration/app/config/initializers/mime_types.rb
-test/integration/app/config/routes.rb
-test/integration/app/doc/README_FOR_APP
-test/integration/app/public/404.html
-test/integration/app/public/422.html
-test/integration/app/public/500.html
-test/integration/app/public/dispatch.cgi
-test/integration/app/public/dispatch.fcgi
-test/integration/app/public/dispatch.rb
-test/integration/app/public/favicon.ico
-test/integration/app/public/images/rails.png
-test/integration/app/public/javascripts/application.js
-test/integration/app/public/javascripts/controls.js
-test/integration/app/public/javascripts/dragdrop.js
-test/integration/app/public/javascripts/effects.js
-test/integration/app/public/javascripts/prototype.js
-test/integration/app/public/robots.txt
-test/integration/app/Rakefile
-test/integration/app/README
-test/integration/app/script/about
-test/integration/app/script/console
-test/integration/app/script/destroy
-test/integration/app/script/generate
-test/integration/app/script/performance/benchmarker
-test/integration/app/script/performance/profiler
-test/integration/app/script/performance/request
-test/integration/app/script/plugin
-test/integration/app/script/process/inspector
-test/integration/app/script/process/reaper
-test/integration/app/script/process/spawner
-test/integration/app/script/runner
-test/integration/app/script/server
-test/integration/app/test/functional/items_controller_test.rb
-test/integration/app/test/test_helper.rb
-test/integration/server_test.rb
-test/misc/direct.rb
+ruby/bleak_house.patch
+ruby/configure.patch
+ruby/gc.patch
+ruby/ruby-1.8.6-p114.tar.bz2
+ruby/valgrind.patch
+test/benchmark/bench.rb
 test/test_helper.rb
 test/unit/test_bleak_house.rb
 TODO

data/README

@@ -14,15 +14,15 @@ If you use this software, please {make a donation}[http://blog.evanweaver.com/do
 == Features
 
 * leak-proof C instrumentation
-* tracks all objects and symbols
-* inspection of sample leaked objects (optional)
-* easy Rails integration
+* minimal impact on runtime performance
+* fast analysis step
+* tracks all objects allocated on the heap, including internal types like <tt>T_NODE</tt>
+* easy integration in any program, not just Rails
 
 == Requirements
 
 * A unix-like operating system
 * Ruby 1.8.6
-* Rails 1.2.x or 2.0.x
 
 = Usage
 
@@ -35,38 +35,74 @@ The installation takes a long time because it compiles a patched Ruby binary for
 
 Please see the forum ( http://rubyforge.org/forum/forum.php?forum_id=13983 ) if you have installation problems.
 
-== Profiling a Rails app
+== Usage
 
-To setup a Rails app for profiling, just <tt>require 'bleak_house'</tt> in <tt>config/environment.rb</tt>.
+We will profile a Rails app as an example. Note that BleakHouse works equally well in any Ruby program.
 
-Then, to engage the logger (ideally, in a live deployment situation), start a server instance as so:
-  RAILS_ENV=production BLEAK_HOUSE=true ruby-bleak-house ./script/server 
+First, to setup the app for profiling, add the following at the bottom of <tt>config/environment.rb</tt>:
+  require 'bleak_house' if ENV['BLEAK_HOUSE']
 
-Browse around manually, thrash your entire app with a script, target troublesome controllers/actions, etc. The BleakHouse logger will dump a huge amount of data to <tt>log/bleak_house_production.dump</tt>--keep an eye on your disk space. I usually aim for a 3GB dump.
+Then, to engage the logger (possibly in a live deployment situation), start a server instance as so:
+  RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server 
 
-Then, to analyze the dump:
-  bleak path/to/log/bleak_house_production.dump
-  
-Be patient; it's quite slow.
+Look for the message:
+  ** Bleakhouse: installed  
+
+Browse around manually, thrash your entire app with a script, target troublesome controllers/actions, etc. After a couple hundred requests, hit CTRL-C. The server will stop and BleakHouse will produce a dumpfile in <tt>/tmp</tt>:
 
-== Sampling object contents
+  ** BleakHouse: working...
+  ** BleakHouse: complete
+  ** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.
 
-BleakHouse can sample object contents, which might help you figure out the source of the leak. Just add <tt>SAMPLE_RATE=0.1</tt> to the environment string when you start your server. 
+To analyse it, just run the listed command. The top 20 leakiest lines will be listed:
+
+  191691 total objects
+  Final heap size 191691 filled, 220961 free
+  Displaying top 20 most common line/class pairs
+  89513 __null__:__null__:__node__
+  41438 __null__:__null__:String
+  2348 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:Array
+  1508 /opt/local//lib/ruby/gems/1.8/specifications/gettext-1.90.0.gemspec:14:String
+  1021 /opt/local//lib/ruby/gems/1.8/specifications/heel-0.2.0.gemspec:14:String
+   951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String
+   935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String
+   834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array
+  ...
+  
+You can pass an integer as the second parameter to <tt>bleak</tt> if you want to see more lines than the default.
 
-Note that there is a chance this could _introduce_ leaks if you override <tt>inspect</tt> in leaky ways. Unfortunately, the samping is of dubious usefulness and really increases the memory usage of the analyze task. That's why it's off by default. 
+The underscored types are special Ruby internal structs, but can be real leaks just as easily as fullblown classes. 
+
+Do not try to detect Rails leaks in <tt>development</tt> mode. Make a separate <tt>benchmark</tt> environment if you need to, and make sure all your production caching is turned on.
 
 = Extras
 
-== Using BleakHouse outside of Rails
+== Injecting a signal
+
+You can send <tt>SIGUSR2</tt> to a BleakHouse-instrumented program to snag a dump at any time. Once the dump completes, the program will continue to run. Dumps are named based on the host process id, and sequential dumps are numbered in ascending order.
 
-Just instantiate a BleakHouse::Logger object, and make calls to <tt>snapshot</tt> at appropriate times, with tags to identify their context.
+== Tips
 
-== Troubleshooting
+It is normal to see lots of <tt>null:null</tt> references, especially for nodes. Using <tt>eval()</tt> too much can be a cause of node leaks. You can track <tt>eval()</tt> by using sourceline macros in your code:
 
-If you see the error <tt>Symbol not found: _rb_gc_heaps_used</tt>, it means you installed the patched binary, but tried to profile the server with the regular Ruby binary.
+  eval("CODE", nil, __FILE__, __LINE__)
 
 You may get library require errors if you install <tt>ruby-bleak-house</tt> 1.8.6 alongside a different verson of Ruby. You could try to patch your local version of Ruby instead, or you could just upgrade to 1.8.6, which has a good trackrecord of stability.
 
+It is not recommended that you use <tt>ruby-bleak-house</tt> as your production Ruby binary, since it will be slightly slower and use slightly more memory. It is unlikely, however, to affect stability.
+
+If BleakHouse doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or have encounted a {real leak in the interpreter}[http://groups.google.com/group/god-rb/browse_thread/thread/1cca2b7c4]. Try using Valgrind[http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/] instead.
+
+== Methods
+
+The easiest way to fix a leak is to make it repeatable. 
+
+First, write a script that exercises your app in a deterministic way. Run it for a small number of loops; then run <tt>bleak</tt>. Then run it for a larger number of loops, and run <tt>bleak</tt> again. The lines that grow significantly between runs are your leaks for that codepath.
+
+Now, look at those lines in the source and try to figure out what references them. Where do the return values go? Add some breakpoints or output backtraces to <tt>STDERR</tt> as you go. Eventually you should find a point where it is relatively clear that a reference is getting maintained. 
+
+Try to remove that reference, run your script again, and see if the object counts have dropped.
+
 == Reporting problems
 
 The support forum is here[http://rubyforge.org/forum/forum.php?forum_id=13983].
@@ -75,6 +111,7 @@ Patches and contributions are very welcome. Please note that contributors are re
 
 == Further resources
 
+* http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/
 * http://blog.evanweaver.com/articles/2007/05/12/let-me-hit-you-with-some-knowledge
 * http://blog.evanweaver.com/articles/2007/05/06/leak-proof-direct-heap-instrumentation-for-bleak_house
 * http://blog.evanweaver.com/articles/2007/04/28/bleak_house

data/TODO

@@ -1,3 +1,3 @@
 
-* Better docs on what the tags mean
-* Use per-frame file storage to avoid out-of-memory problems
+* Add some kind of delta support
+* Log several levels of the backtrace instead of just the current node's information

data/bin/bleak

@@ -8,19 +8,6 @@ if !ARGV[0]
 else
   $LOAD_PATH << "#{File.dirname(__FILE__)}/../lib/"
   require 'bleak_house/analyzer'
-
   require 'ruby-debug' if ENV['DEBUG']
-
-  if ENV['WATCH_MEM']
-    Thread.new do
-      while sleep(10)
-        free = `free -m`.split("\n")[2].split(" ")[3].to_i
-        if free < 20
-          exit!
-        end
-      end
-    end
-  end
-
-  BleakHouse::Analyzer.run(ARGV[0])
+  BleakHouse::Analyzer.run(ARGV[0], ARGV[1] || 20)
 end

data/bleak_house.gemspec

@@ -1,33 +1,31 @@
 
-# Gem::Specification for Bleak_house-3.7.1
+# Gem::Specification for Bleak_house-4.0
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{bleak_house}
-  s.version = "3.7.1"
+  s.version = "4.0"
 
   s.specification_version = 2 if s.respond_to? :specification_version=
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Evan Weaver"]
-  s.date = %q{2008-03-30}
+  s.date = %q{2008-04-06}
   s.default_executable = %q{bleak}
   s.description = %q{A library for finding memory leaks.}
   s.email = %q{}
   s.executables = ["bleak"]
-  s.extensions = ["ext/bleak_house/logger/extconf.rb"]
-  s.extra_rdoc_files = ["CHANGELOG", "ext/bleak_house/logger/snapshot.c", "lib/bleak_house/analyzer/analyzer.rb", "lib/bleak_house/analyzer.rb", "lib/bleak_house/logger/source.rb", "lib/bleak_house/logger.rb", "lib/bleak_house/rails/bleak_house.rb", "LICENSE", "LICENSE_BSD", "README", "TODO"]
-  s.files = ["bin/bleak", "CHANGELOG", "ext/bleak_house/logger/build_logger.rb", "ext/bleak_house/logger/build_ruby.rb", "ext/bleak_house/logger/extconf.rb", "ext/bleak_house/logger/snapshot.c", "ext/bleak_house/logger/snapshot.h", "init.rb", "install.rb", "lib/bleak_house/analyzer/analyzer.rb", "lib/bleak_house/analyzer.rb", "lib/bleak_house/logger/source.rb", "lib/bleak_house/logger.rb", "lib/bleak_house/rails/action_controller.rb", "lib/bleak_house/rails/bleak_house.rb", "lib/bleak_house/rails/dispatcher.rb", "lib/bleak_house/rails.rb", "lib/bleak_house/support/core_extensions.rb", "lib/bleak_house.rb", "LICENSE", "LICENSE_BSD", "Manifest", "README", "ruby/gc.c.patch", "ruby/parse.y.patch", "ruby/ruby-1.8.6-p110.tar.bz2", "test/integration/app/app/controllers/application.rb", "test/integration/app/app/controllers/items_controller.rb", "test/integration/app/app/helpers/application_helper.rb", "test/integration/app/app/helpers/items_helper.rb", "test/integration/app/app/views/items/index.rhtml", "test/integration/app/config/boot.rb", "test/integration/app/config/database.yml", "test/integration/app/config/environment.rb", "test/integration/app/config/environments/development.rb", "test/integration/app/config/environments/production.rb", "test/integration/app/config/environments/test.rb", "test/integration/app/config/initializers/inflections.rb", "test/integration/app/config/initializers/mime_types.rb", "test/integration/app/config/routes.rb", "test/integration/app/doc/README_FOR_APP", "test/integration/app/public/404.html", "test/integration/app/public/422.html", "test/integration/app/public/500.html", "test/integration/app/public/dispatch.cgi", "test/integration/app/public/dispatch.fcgi", "test/integration/app/public/dispatch.rb", "test/integration/app/public/favicon.ico", "test/integration/app/public/images/rails.png", "test/integration/app/public/javascripts/application.js", "test/integration/app/public/javascripts/controls.js", "test/integration/app/public/javascripts/dragdrop.js", "test/integration/app/public/javascripts/effects.js", "test/integration/app/public/javascripts/prototype.js", "test/integration/app/public/robots.txt", "test/integration/app/Rakefile", "test/integration/app/README", "test/integration/app/script/about", "test/integration/app/script/console", "test/integration/app/script/destroy", "test/integration/app/script/generate", "test/integration/app/script/performance/benchmarker", "test/integration/app/script/performance/profiler", "test/integration/app/script/performance/request", "test/integration/app/script/plugin", "test/integration/app/script/process/inspector", "test/integration/app/script/process/reaper", "test/integration/app/script/process/spawner", "test/integration/app/script/runner", "test/integration/app/script/server", "test/integration/app/test/functional/items_controller_test.rb", "test/integration/app/test/test_helper.rb", "test/integration/server_test.rb", "test/misc/direct.rb", "test/test_helper.rb", "test/unit/test_bleak_house.rb", "TODO", "bleak_house.gemspec"]
+  s.extensions = ["ext/extconf.rb"]
+  s.extra_rdoc_files = ["CHANGELOG", "ext/snapshot.c", "lib/bleak_house/analyzer.rb", "lib/bleak_house/hook.rb", "lib/bleak_house.rb", "LICENSE", "LICENSE_BSD", "README", "TODO"]
+  s.files = ["bin/bleak", "CHANGELOG", "ext/build_ruby.rb", "ext/build_snapshot.rb", "ext/extconf.rb", "ext/snapshot.c", "ext/snapshot.h", "lib/bleak_house/analyzer.rb", "lib/bleak_house/hook.rb", "lib/bleak_house.rb", "LICENSE", "LICENSE_BSD", "Manifest", "README", "ruby/bleak_house.patch", "ruby/configure.patch", "ruby/gc.patch", "ruby/ruby-1.8.6-p114.tar.bz2", "ruby/valgrind.patch", "test/benchmark/bench.rb", "test/test_helper.rb", "test/unit/test_bleak_house.rb", "TODO", "bleak_house.gemspec"]
   s.has_rdoc = true
   s.homepage = %q{http://blog.evanweaver.com/files/doc/fauna/bleak_house/}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Bleak_house", "--main", "README"]
   s.require_paths = ["lib", "ext"]
   s.rubyforge_project = %q{fauna}
-  s.rubygems_version = %q{1.0.1}
+  s.rubygems_version = %q{1.1.0}
   s.summary = %q{A library for finding memory leaks.}
-  s.test_files = ["test/integration/server_test.rb", "test/unit/test_bleak_house.rb"]
-
-  s.add_dependency(%q<ccsv>, [">= 0.1"])
+  s.test_files = ["test/test_helper.rb", "test/unit/test_bleak_house.rb"]
 end
 
 
@@ -42,10 +40,6 @@ end
 #   p.summary = "A library for finding memory leaks."  
 #   p.url = "http://blog.evanweaver.com/files/doc/fauna/bleak_house/"  
 #   p.docs_host = 'blog.evanweaver.com:~/www/bax/public/files/doc/'
-#   p.dependencies = ['ccsv >=0.1'] # 'memory >=0.0.2'
-#   p.require_signed = true
-#   
-#   p.rdoc_pattern = /^ext.*\.c|lib.*logger.*rb|analyzer|rails\/bleak_house|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/
-#   p.test_pattern = ["test/integration/*.rb", "test/unit/*.rb"]
-#   p.clean_pattern << "**/bleak_house*dump*"
+#   p.require_signed = true  
+#   p.rdoc_pattern = /^ext.*\.c|lib.*|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/
 # end

data/ext/{bleak_house/logger/build_ruby.rb → build_ruby.rb}

@@ -9,7 +9,7 @@ unless RUBY_VERSION == '1.8.6'
   raise "Wrong Ruby version, you're at '#{RUBY_VERSION}', need 1.8.6"
 end
 
-source_dir = File.expand_path(File.dirname(__FILE__)) + "/../../../ruby"
+source_dir = File.expand_path(File.dirname(__FILE__)) + "/../ruby"
 tmp = "/tmp/"
 
 require 'fileutils'
@@ -23,30 +23,40 @@ def which(basename)
   end
 end
 
-unless which('ruby-bleak-house')
-  
+if which('ruby-bleak-house') and 
+  `ruby-bleak-house -e "puts RUBY_PATCHLEVEL"`.to_i > 900
+  # OK
+else
+  # Build  
   Dir.chdir(tmp) do
     build_dir = "bleak_house"
     binary_dir = File.dirname(`which ruby`)
+    
     FileUtils.rm_rf(build_dir) rescue nil
+    if File.exist? build_dir
+      raise "Could not delete previous build dir #{Dir.pwd}/#{build_dir}"
+    end
+    
     Dir.mkdir(build_dir)
   
     begin
       Dir.chdir(build_dir) do
   
         # Copy Ruby source
-        bz2 = "ruby-1.8.6-p110.tar.bz2"
+        bz2 = "ruby-1.8.6-p114.tar.bz2"
         FileUtils.copy "#{source_dir}/#{bz2}", bz2
   
         # Extract
         system("tar xjf #{bz2} > tar.log 2>&1")
         File.delete bz2
     
-        Dir.chdir("ruby-1.8.6-p110") do
+        Dir.chdir("ruby-1.8.6-p114") do
   
           # Patch, configure, and build
-          system("patch -p0 < \'#{source_dir}/gc.c.patch\' > ../gc.c.patch.log 2>&1")
-          system("patch -p0 < \'#{source_dir}/parse.y.patch\' > ../parse.y.patch.log 2>&1")
+          ["valgrind", "configure", "gc"].each do |patch|
+            system("patch -p0 < \'#{source_dir}/#{patch}.patch\' > ../#{patch}_patch.log 2>&1")
+          end
+ 
           system("./configure --prefix=#{binary_dir[0..-5]} > ../configure.log 2>&1") # --with-static-linked-ext
           
           # Patch the makefile for arch/sitedir

data/ext/build_snapshot.rb

@@ -0,0 +1,4 @@
+require 'mkmf'
+$CFLAGS = ENV['CFLAGS']
+dir_config('snapshot')
+create_makefile('snapshot')

data/ext/{bleak_house/logger/extconf.rb → extconf.rb}

@@ -1,3 +1,3 @@
 
 system('ruby build_ruby.rb &> /dev/null')
-exec('ruby-bleak-house build_logger.rb')
+exec('ruby-bleak-house build_snapshot.rb')

data/ext/snapshot.c

@@ -0,0 +1,157 @@
+#include <time.h>
+#include "snapshot.h"
+
+static VALUE rb_mB;
+static VALUE rb_cC;
+
+/* Number of filled <tt>heaps_slots</tt> */
+static VALUE heaps_used(VALUE self) {
+  return INT2FIX(rb_gc_heaps_used());
+}
+
+/* Number of allocated <tt>heaps_slots</tt> */
+static VALUE heaps_length(VALUE self) {
+  return INT2FIX(rb_gc_heaps_length());
+}
+
+/* Walk the live, instrumented objects on the heap and write them to <tt>_logfile</tt>. */
+static VALUE snapshot(VALUE self, VALUE _logfile) {
+  Check_Type(_logfile, T_STRING);
+
+  RVALUE *obj, *obj_end;
+  st_table_entry *sym; 
+  
+  struct heaps_slot * heaps = rb_gc_heap_slots();
+  struct st_table * sym_tbl = rb_parse_sym_tbl();
+
+  /* see if the logfile exists already */
+  FILE *logfile = fopen(StringValueCStr(_logfile), "r");
+  int is_new;
+  if (!(is_new = (logfile == NULL)))
+    fclose(logfile);
+
+  /* reopen for writing */
+  if ((logfile = fopen(StringValueCStr(_logfile), "w")) == NULL)
+    rb_raise(rb_eRuntimeError, "couldn't open snapshot file");
+
+  int filled_slots = 0;
+  int free_slots = 0;
+
+  int i; 
+  char * chr;
+    
+  for (i = 0; i < 3; i++) {
+    /* request GC run */
+    rb_funcall(rb_mGC, rb_intern("start"), 0);
+    rb_thread_schedule();
+  }
+  
+  /* walk the heap */
+  for (i = 0; i < rb_gc_heaps_used(); i++) {
+    obj = heaps[i].slot;
+    obj_end = obj + heaps[i].limit;
+    for (; obj < obj_end; obj++) {
+      if (obj->as.basic.flags) { /* always 0 for freed objects */
+        filled_slots ++;
+        
+        /* write the source file*/
+        if (obj->file) {
+          chr = obj->file;          
+          if (*chr != '\0') {
+            /* replace unprintable characters */
+            for (; *chr; chr++) {
+              if ((*chr < 33) || (*chr > 126)) {
+                fputc('_', logfile);
+              } else {
+                fputc(*chr, logfile);
+              }
+            }
+          } else {
+            fprintf(logfile, "__empty__");   
+          }
+        } else {
+          fprintf(logfile, "__null__");
+        }
+        
+        /* write the source line */
+        fprintf(logfile, ":");        
+        if (obj->line) {
+          fprintf(logfile, "%i", obj->line);
+        } else {
+          fprintf(logfile, "__null__");
+        }
+        
+        /* write the class */
+        fprintf(logfile, ":");
+        switch (TYPE(obj)) {
+          case T_NONE:
+              fprintf(logfile, "__none__"); break;
+          case T_BLKTAG:
+              fprintf(logfile, "__blktag__"); break;
+          case T_UNDEF:
+              fprintf(logfile, "__undef__"); break;
+          case T_VARMAP:
+              fprintf(logfile, "__varmap__"); break;
+          case T_SCOPE:
+              fprintf(logfile, "__scope__"); break;
+          case T_NODE:
+              fprintf(logfile, "__node__"); break;
+          default:
+            if (!obj->as.basic.klass) {
+              fprintf(logfile, "__unknown__");
+            } else {
+              fprintf(logfile, rb_obj_classname((VALUE)obj));
+            }
+        }
+        
+        /* write newline */
+        fprintf(logfile, "\n");
+      } else {
+        free_slots ++;
+      }
+    }
+  }
+  
+  /* walk the symbol table */  
+  /* hashed = lookup_builtin("Symbol");
+  for (i = 0; i < sym_tbl->num_bins; i++) {
+    for (sym = sym_tbl->bins[i]; sym != 0; sym = sym->next) {
+      fprintf(logfile, "%i,%lu\n", hashed + 1, sym->record);
+    }
+  } */
+    
+  fprintf(logfile, "%i filled\n", filled_slots);
+  fprintf(logfile, "%i free\n", free_slots);
+  fclose(logfile);
+  
+  return Qnil;
+}
+
+
+/*
+
+This class performs the actual object logging of BleakHouse. To use it directly, you need to make calls to BleakHouse.snapshot. 
+
+By default, BleakHouse records a snapshot on exit. You can disable this by setting the environment variable <tt>NO_EXIT_HANDLER</tt> before startup. 
+
+It is also possible to externally trigger the snapshot at any time by sending <tt>SIGUSR2</tt> to the process. 
+
+== Example
+
+At the start of your app, put:
+  require 'rubygems'
+  require 'bleak_house'
+  $logfile = "/path/to/logfile"
+
+Run your app. Once it exits, analyze your data:
+  bleak /path/to/logfile
+  
+*/
+void
+Init_snapshot()
+{
+  rb_mB = rb_define_module("BleakHouse");
+  rb_define_singleton_method(rb_mB, "snapshot", snapshot, 1);
+  rb_define_singleton_method(rb_mB, "heaps_used", heaps_used, 0);
+  rb_define_singleton_method(rb_mB, "heaps_length", heaps_length, 0);
+}