Leaky

Leaky is a program which will help you find memory leaks, and as of late, help you debug reference count problems with xpcom objects.

Get the Source

Leaky is not currently part of the default SeaMonkey module,
you will need to explicitly pull the source:
  

  cvs checkout mozilla/tools/leaky
If there is enough demand, we can make this part of the default SeaMonkey module.

Building it
  

  ./configure --enable-leaky
Top-of-tree build should Just Build It and leaky will show up in dist/bin.

Using Leaky

After it has been built, you can use TestPreload and TestMalloc and ShowLibs to debug your implementation.

By setting the LIBMALLOC_LOG environment variable you control how much information is logged during the programs execution. See libmalloc.h for a definition of the values to use. If you are using LD_PRELOAD, here is one way to run your program:

env LD_PRELOAD=/full/path/to/libleaky.so LIBMALLOC_LOG=1 my-program
The debugging malloc library creates two files, malloc-log and malloc-map. The malloc-log file can be quite large for large programs (e.g. mozilla) so be prepared to have alot of disk space. The malloc-map is tiny.

Once your program has completed execution you can use leaky to look for memory leaks, or at least use it to dump the log. For memory leaks, you use leaky like this:

leaky -d <program-name-goes-here> malloc-log
Leaky will then display all of the call sites where memory was leaked. To look at the entire log file contents, not just the leaks add "-a" to the arguments:
leaky -d -a <program-name-goes-here> malloc-log
For debugging reference count issues, here is what I do:
  1. Set LIBMALLOC_LOG to "8"
  2. Modify your source code so that your class::Addref and class::Release methods call __log_addref and __log_release, as appropriate. See libmalloc.h for their signatures. If you are using mozilla, you no longer need to modify your source code with a debug build. See xpcom/doc/MemoryTools.html for more info.
  3. Run your program so that you get the log data. Its often convenient to run your program in the debugger and then set a breakpoint at an interesting location where you think some object is being leaked or over-freed. Then when the debugger gets there tell it to execute DumpAddressMap. In gdb you do this:
      4.  
      (gdb) p DumpAddressMap()
  4. Then use leaky to capture the addref and release calls to a log file:
      5.  
      leaky -d -a <program-name-goes-here> malloc-log > log
  5. Then use "grep" to search the log for a specific object by grepping for its memory address...
  6. On a typical *short* run of mozilla, I'll end up with a malloc-log file of around 5 to 10 megabytes and the resulting converted log file will be 10 to 20 times that so be prepared to have alot of disk space. It helps a great deal to narrow down your problem space to reduce the log file size...


Leaky now has a "graph" output option. If you do this: 

  leaky -gqx <program-name-goes-here>  malloc-log | sed -e 's/&/&/g' > /tmp/GQ0.html
Then leaky will make a graph of the leaks [-g] and output that graph in xml format (currently actually html...) [-x]. I use sed to make it legitimate html and off it goes to a file.

If you throw file at viewer (recursion is cool) then it will present you with a treeview of the leaks that you can click on to open/close sections. Enjoy!

Command Line Options
 
-a dump the entire log. This means all malloc's, free's, new's, delete's, addref's or release's will be displayed
-d dump leaks (only one of -d, -R or -g can be used at a time)
-R dump refcnts
   
-g display a graph of leaks
-x when displaying the graph with -g, use html output that can be fed into an html4+css+dom compliant viewer (like mozilla :-)
-r symbol define a root for the graph dump. nodes in the graph above symbol will be hidden, thus reducing the depth of the graph making it easier to find deeper leaks.
   
-e symbol exclude leaks that include symbol from treatment
-i symbol include leaks that include symbol for treatment. If an includes are defined than only leaks which include the symbols will be processed. excludes will still apply to this reduced set of leaks
   
-A show the address in the stack crawls, not just the symobls
-h num set the size of the hash buckets used by leaksy dictionaries to <num>
-s depth set the depth of the stack crawls shown when displaying stack crawls (any of the dumping modes except -g)
-q make leaky quiet (don't dump the information about symbols being read and from which libraries)

Porting to non-Intel/Linux
 

Initial version works only on x86 linux. To work on other platforms you will need to:

  1. Implement CrawlStack() in libmalloc.cpp
  2. Implement DumpAddressMap() in libmalloc.cpp and in ShowLibs.cpp
  3. Either support LD_PRELOAD in your dynamic linker, or

    4. produce a library that wraps your libc malloc (see config.h for some clues)
  4. Implement symbol table reading code (see coff.cpp, elf.cpp and bfd.cpp for examples; at the time of writing this document only bfd.cpp was known to work)
Last modified: Sun Sep 26 13:15:33 PDT 1999
Send comments to Kipp Hickman