In addition to profiling the time and allocation behaviour of your program, you can also generate a graph of its memory usage over time. This is useful for detecting the causes of space leaks, when your program holds on to more memory at run-time that it needs to. Space leaks lead to longer run-times due to heavy garbage collector activity, and may even cause the program to run out of memory altogether.
To generate a heap profile from your program:
Compile the program for profiling (Section 5.2, “Compiler options for profiling”).
Run it with one of the heap profiling options described
below (eg. -hc for a basic producer profile).
This generates the file
prog.hp
Run hp2ps to produce a Postscript
file,
prog.ps
Display the heap profile using a postscript viewer such as Ghostview, or print it out on a Postscript-capable printer.
You might also want to take a look at hp2any, a more advanced suite of tools (not distributed with GHC) for displaying heap profiles.
There are several different kinds of heap profile that can be generated. All the different profile types yield a graph of live heap against time, but they differ in how the live heap is broken down into bands. The following RTS options select which break-down to use:
-hc
Breaks down the graph by the cost-centre stack which produced the data.
-hm
Break down the live heap by the module containing the code which produced the data.
-hd
Breaks down the graph by closure description. For actual data, the description is just the constructor name, for other closures it is a compiler-generated string identifying the closure.
-hy
Breaks down the graph by type. For closures which have function type or unknown/polymorphic type, the string will represent an approximation to the actual type.
-hr
Break down the graph by retainer set. Retainer profiling is described in more detail below (Section 5.4.2, “Retainer Profiling”).
-hb
Break down the graph by biography. Biographical profiling is described in more detail below (Section 5.4.3, “Biographical Profiling”).
In addition, the profile can be restricted to heap data which satisfies certain criteria - for example, you might want to display a profile by type but only for data produced by a certain module, or a profile by retainer for a certain type of data. Restrictions are specified as follows:
-hcname,...
Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres at the top.
-hCname,...
Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres anywhere in the stack.
-hmmodule,...
Restrict the profile to closures produced by the specified modules.
-hddesc,...
Restrict the profile to closures with the specified description strings.
-hytype,...
Restrict the profile to closures with the specified types.
-hrcc,...
Restrict the profile to closures with retainer sets containing cost-centre stacks with one of the specified cost centres at the top.
-hbbio,...
Restrict the profile to closures with one of the
specified biographies, where
bio is one of
lag, drag,
void, or use.
For example, the following options will generate a
retainer profile restricted to Branch and
Leaf constructors:
prog +RTS -hr -hdBranch,Leaf
There can only be one "break-down" option
(eg. -hr in the example above), but there is no
limit on the number of further restrictions that may be applied.
All the options may be combined, with one exception: GHC doesn't
currently support mixing the -hr and
-hb options.
There are three more options which relate to heap profiling:
-isecs:
Set the profiling (sampling) interval to
secs seconds (the default is
0.1 second). Fractions are allowed: for example
-i0.2 will get 5 samples per second.
This only affects heap profiling; time profiles are always
sampled on a 1/50 second frequency.
-xt
Include the memory occupied by threads in a heap profile. Each thread takes up a small area for its thread state in addition to the space allocated for its stack (stacks normally start small and then grow as necessary).
This includes the main thread, so using
-xt is a good way to see how much stack
space the program is using.
Memory occupied by threads and their stacks is labelled as “TSO” when displaying the profile by closure description or type description.
-Lnum
Sets the maximum length of a cost-centre stack name in a heap profile. Defaults to 25.
Retainer profiling is designed to help answer questions like “why is this data being retained?”. We start by defining what we mean by a retainer:
A retainer is either the system stack, or an unevaluated closure (thunk).
In particular, constructors are not retainers.
An object B retains object A if (i) B is a retainer object and (ii) object A can be reached by recursively following pointers starting from object B, but not meeting any other retainer objects on the way. Each live object is retained by one or more retainer objects, collectively called its retainer set, or its retainer set, or its retainers.
When retainer profiling is requested by giving the program
the -hr option, a graph is generated which is
broken down by retainer set. A retainer set is displayed as a
set of cost-centre stacks; because this is usually too large to
fit on the profile graph, each retainer set is numbered and
shown abbreviated on the graph along with its number, and the
full list of retainer sets is dumped into the file
prog.prof
Retainer profiling requires multiple passes over the live
heap in order to discover the full retainer set for each
object, which can be quite slow. So we set a limit on the
maximum size of a retainer set, where all retainer sets larger
than the maximum retainer set size are replaced by the special
set MANY. The maximum set size defaults to 8
and can be altered with the -R RTS
option:
-RsizeRestrict the number of elements in a retainer set to
size (default 8).
The definition of retainers is designed to reflect a
common cause of space leaks: a large structure is retained by
an unevaluated computation, and will be released once the
computation is forced. A good example is looking up a value in
a finite map, where unless the lookup is forced in a timely
manner the unevaluated lookup will cause the whole mapping to
be retained. These kind of space leaks can often be
eliminated by forcing the relevant computations to be
performed eagerly, using seq or strictness
annotations on data constructor fields.
Often a particular data structure is being retained by a chain of unevaluated closures, only the nearest of which will be reported by retainer profiling - for example A retains B, B retains C, and C retains a large structure. There might be a large number of Bs but only a single A, so A is really the one we're interested in eliminating. However, retainer profiling will in this case report B as the retainer of the large structure. To move further up the chain of retainers, we can ask for another retainer profile but this time restrict the profile to B objects, so we get a profile of the retainers of B:
prog +RTS -hr -hcB
This trick isn't foolproof, because there might be other B closures in the heap which aren't the retainers we are interested in, but we've found this to be a useful technique in most cases.
A typical heap object may be in one of the following four states at each point in its lifetime:
The lag stage, which is the time between creation and the first use of the object,
the use stage, which lasts from the first use until the last use of the object, and
The drag stage, which lasts from the final use until the last reference to the object is dropped.
An object which is never used is said to be in the void state for its whole lifetime.
A biographical heap profile displays the portion of the live heap in each of the four states listed above. Usually the most interesting states are the void and drag states: live heap in these states is more likely to be wasted space than heap in the lag or use states.
It is also possible to break down the heap in one or more of these states by a different criteria, by restricting a profile by biography. For example, to show the portion of the heap in the drag or void state by producer:
prog +RTS -hc -hbdrag,void
Once you know the producer or the type of the heap in the drag or void states, the next step is usually to find the retainer(s):
prog+RTS -hr -hccc...
NOTE: this two stage process is required because GHC cannot currently profile using both biographical and retainer information simultaneously.
How does the heap residency reported by the heap profiler relate to
the actual memory residency of your program when you run it? You might
see a large discrepancy between the residency reported by the heap
profiler, and the residency reported by tools on your system
(eg. ps or top on Unix, or the
Task Manager on Windows). There are several reasons for this:
There is an overhead of profiling itself, which is subtracted from the residency figures by the profiler. This overhead goes away when compiling without profiling support, of course. The space overhead is currently 2 extra words per heap object, which probably results in about a 30% overhead.
Garbage collection requires more memory than the actual
residency. The factor depends on the kind of garbage collection
algorithm in use: a major GC in the standard
generation copying collector will usually require 3L bytes of
memory, where L is the amount of live data. This is because by
default (see the +RTS -F option) we allow the old
generation to grow to twice its size (2L) before collecting it, and
we require additionally L bytes to copy the live data into. When
using compacting collection (see the +RTS -c
option), this is reduced to 2L, and can further be reduced by
tweaking the -F option. Also add the size of the
allocation area (currently a fixed 512Kb).
The stack isn't counted in the heap profile by default. See the
+RTS -xt option.
The program text itself, the C stack, any non-heap data (eg. data
allocated by foreign libraries, and data allocated by the RTS), and
mmap()'d memory are not counted in the heap profile.