Reorganisation of the source tree

[ghc-hetmet.git] / utils / heap-view / README

diff --git a/utils/heap-view/README b/utils/heap-view/README
new file mode 100644 (file)
index 0000000..db9503a
--- /dev/null
+++ b/utils/heap-view/README
@@ -0,0 +1,62 @@
+@HpView.lhs@ is a very primitive heap profile viewer written in
+Haskell.  It feeds off the same files as hp2ps.  It needs a lot of
+tidying up and would be far more useful as a continuous display.
+(It's in this directory `cos there happens to be a heap profile here
+and I couldn't be bothered setting up a new directory, Makefile, etc.)
+
+@Graph.lhs@ is a continuous heap viewer that "parses" the output of
+the +RTS -Sstderr option.  Typical usage:
+
+   slife 1 r4 +RTS -Sstderr |& graph 2
+
+(You might also try 
+
+   cat data | graph 2
+
+ to see it in action on some sample data.
+)
+
+Things to watch:
+
+  1) Scaling varies from column to column - consult the source.
+
+  2) The horizontal scale is not time - it is garbage collections.
+
+  3) The graph is of the (n+1)st column of the -Sstderr output. 
+
+     The data is not always incredibly useful: For example, when using
+     the (default) Appel 2-space garbage collector, the 3rd column
+     displays the amount of "live" data in the minor space.  A program
+     with a constant data usage will appear to have a sawtooth usage
+     as minor data gradually transfers to the major space and then,
+     suddenly, all gets transferred back at major collections.
+     Decreasing heap size decreases the size of the minor collections
+     and increases major collections exaggerating the sawtooth.
+
+  4) The program is not as robust as it might be.
+
+
+@HpView2.lhs@ is the result of a casual coupling of @Graph.lhs@ and
+@HpView.lhs@ which draws continuous graphs of the heap consisting of:
+total usage and usage by one particular cost centre.  For example:
+
+    mkfifo slife.hp
+    hpView2 slife.hp Main:mkQuad &
+    slife 2 Unis/gardenofeden +RTS -h -i0.1 -RTS 
+    rm slife.hp
+
+draws a graph of total usage and usage by the function @mkQuad@.  
+
+(You might also try 
+
+       hpView2 slife.old-hp Main:mkQuad
+
+ to see it in action on some older data)
+
+The business with named pipes (mkfifo) is a little unfortunate - it
+would be nicer if the Haskell runtime system could output to stderr
+(say) which I could pipe into hpView which could just graph it's stdin
+(like graph does).  It's probably worth wrapping the whole thing up in
+a little shell-script.
+
+