Refgraph

This is being superseded by DMD, see bug 1014346

Refgraph, a mozilla-central fork to study the graph of references between heap objects

Supported platforms

Known to work:

• B2G
• Desktop Linux 64bit

Should work, untested:

• Android
• Desktop Linux 32bit

Not yet supported (pull requests welcome, should not be hard):

• Mac
• Windows

Building and running

Desktop Linux

1. Check out this Git repository:

git clone git@github.com:bjacob/mozilla-central.git mozilla-refgraph
cd mozilla-refgraph

2. Switch to the refgraph branch:

git checkout refgraph

3. Build as usual. This fork takes care of enabling the configure options it needs in configure.in, which are --enable-replace-malloc and --enable-cpp-rtti. No need for --disable-optimize. We don't currently do any stack walking.

4. You should now have two things: an instrumented build of your browser, and a librefgraph.so there:

$OBJDIR/memory/replace/refgraph/librefgraph.so

The two cannot be used without each other.

5. To run your browser, just preload librefgraph, like this:

LD_PRELOAD=$OBJDIR/memory/replace/refgraph/librefgraph.so $OBJDIR/dist/bin/firefox

6. This browser has a special about:refgraph page that has the user interface to refgraph. Navigate to it, click on "Take a snapshot of this browser" and then on "Cycles summary". More detailed usage instructions below.

If you have a build failure, that's not surprising for such a new/immature tool; pull requests welcome.

If the browser fails to run or crashes on startup, the most likely cause would be failure to preload the library. Try setting LD_PRELOAD to an absolute path; verify that librefgraph is preloaded (using e.g. /proc/$PID/maps). Or let me know.

B2G

1. Follow above steps 1. and 2. to get a clone of this repository and switch to the refgraph branch.

2. Point your B2G build environment to it instead of its default gecko tree. One possibility is to add it as a remote in your gecko tree, pull it, and switch to the refgraph branch there. Or you could follow these instructions.

3. Patch your gonk-misc tree with gecko/b2g/refgraph-gonk-misc.patch

4. Build and flash as usual

5. At any time, you can save refgraph snapshots of all B2G processes by running

tools/get_about_memory.py

Notes: **1:**Yes, we currently hijack jlebar's get_about_memory tool to do something different. This is temporary. It will save the snapshots in /data/local/tmp/refgraph-$PID . 2: This hicjacked get_about_memory.py script will stall. Just hit Ctrl-C immediately. 3. Patches very welcome to get our own proper script.

6. Pull these files from the device. You will need to know the PIDs, which you can see with

adb shell b2g-ps

For example if you see that PID 105 is the main process, you could do

adb pull /data/local/tmp/refgraph-105

7. In your desktop browser built with refgraph, go to about:refgraph, enter the snapshot filename under "Load snapshot from file:", hit Load, and start playing (e.g. click Cycles Summary).

Detailed usage instructions

WRITE ME