X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fprofiling.sgml;h=4413eb235ac8b9baca95a68218e3a6aab68a3e0a;hb=f5f6286f3470bc7889460b5ff7db1804f3710323;hp=30175aed34d08c7315145a30fe1a80a0630f1376;hpb=66e87ae1ac00d54df5024033fda5d08db99177a4;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/profiling.sgml b/ghc/docs/users_guide/profiling.sgml
index 30175ae..4413eb2 100644
--- a/ghc/docs/users_guide/profiling.sgml
+++ b/ghc/docs/users_guide/profiling.sgml
@@ -81,7 +81,7 @@ $
will contain something like this:
- Tue Apr 18 12:52 2000 Time and Allocation Profiling Report (Final)
+ Fri May 12 14:06 2000 Time and Allocation Profiling Report (Final)
Main +RTS -p -RTS
@@ -93,15 +93,16 @@ COST CENTRE MODULE %time %alloc
nfib Main 100.0 100.0
-COST CENTRE MODULE scc %time %alloc inner cafs
+ individual inherited
+COST CENTRE MODULE scc %time %alloc %time %alloc
-MAIN MAIN 0 0.0 0.0 0 1
- main Main 0 0.0 0.0 0 1
- CAF PrelHandle 3 0.0 0.0 0 3
- CAF PrelAddr 1 0.0 0.0 0 0
- CAF Main 6 0.0 0.0 1 0
- main Main 1 0.0 0.0 1 1
- nfib Main 242785 100.0 100.0 242784 4
+MAIN MAIN 0 0.0 0.0 100.0 100.0
+ main Main 0 0.0 0.0 0.0 0.0
+ CAF PrelHandle 3 0.0 0.0 0.0 0.0
+ CAF PrelAddr 1 0.0 0.0 0.0 0.0
+ CAF Main 6 0.0 0.0 100.0 100.0
+ main Main 1 0.0 0.0 100.0 100.0
+ nfib Main 242785 100.0 100.0 100.0 100.0
@@ -125,6 +126,12 @@ MAIN MAIN 0 0.0 0.0 0 1
the costly call to nfib came from
main.
+ The time and allocation incurred by a given part of the
+ program is displayed in two ways: “individual”, which
+ are the costs incurred by the code covered by this cost centre
+ stack alone, and “inherited”, which includes the costs
+ incurred by all the children of this node.
+
The usefulness of cost-centre stacks is better demonstrated
by modifying the example slightly:
@@ -139,18 +146,18 @@ nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2)
the new profiling results:
-COST CENTRE MODULE scc %time %alloc inner cafs
-
-MAIN MAIN 0 0.0 0.0 0 1
- main Main 0 0.0 0.0 0 1
- CAF PrelHandle 3 0.0 0.0 0 3
- CAF PrelAddr 1 0.0 0.0 0 0
- CAF Main 9 0.0 0.0 1 1
- main Main 1 0.0 0.0 2 2
- g Main 1 0.0 0.0 1 3
- nfib Main 465 0.0 0.2 464 0
- f Main 1 0.0 0.0 1 1
- nfib Main 242785 100.0 99.8 242784 1
+COST CENTRE MODULE scc %time %alloc %time %alloc
+
+MAIN MAIN 0 0.0 0.0 100.0 100.0
+ main Main 0 0.0 0.0 0.0 0.0
+ CAF PrelHandle 3 0.0 0.0 0.0 0.0
+ CAF PrelAddr 1 0.0 0.0 0.0 0.0
+ CAF Main 9 0.0 0.0 100.0 100.0
+ main Main 1 0.0 0.0 100.0 100.0
+ g Main 1 0.0 0.0 0.0 0.2
+ nfib Main 465 0.0 0.2 0.0 0.2
+ f Main 1 0.0 0.0 100.0 99.8
+ nfib Main 242785 100.0 99.8 100.0 99.8
Now although we had two calls to nfib
@@ -161,7 +168,7 @@ MAIN MAIN 0 0.0 0.0 0 1
- scc
+ entriesThe number of times this particular point in the call
graph was entered.
@@ -169,7 +176,7 @@ MAIN MAIN 0 0.0 0.0 0 1
- %time
+ individual %timeThe percentage of the total run time of the program
spent at this point in the call graph.
@@ -177,7 +184,7 @@ MAIN MAIN 0 0.0 0.0 0 1
- %alloc
+ individual %allocThe percentage of the total memory allocations
(excluding profiling overheads) of the program made by this
@@ -186,19 +193,19 @@ MAIN MAIN 0 0.0 0.0 0 1
- inner
+ inherited %time
- The number of times an inner call-graph context was
- entered from here (including recursive calls).
+ The percentage of the total run time of the program
+ spent below this point in the call graph.
- cafs
+ inherited %alloc
- The number of times a CAF context was entered from
- here. CAFs are described in .
+ The percentage of the total memory allocations
+ (excluding profiling overheads) of the program made by this
+ call and all of its sub-calls.
@@ -249,14 +256,14 @@ MAIN MAIN 0 0.0 0.0 0 1
The syntax of a cost centre annotation is
- _scc_ "name" <expression>
+ {-# SCC "name" #-} <expression>
where "name" is an aribrary string,
that will become the name of your cost centre as it appears
in the profiling output, and
<expression> is any Haskell
- expression. An _scc_ annotation extends as
+ expression. An SCC annotation extends as
far to the right as possible when parsing.
@@ -272,14 +279,14 @@ MAIN MAIN 0 0.0 0.0 0 1
If the expression is part of the
one-off costs of evaluating the
enclosing top-level definition, then costs are attributed to
- the stack of lexically enclosing _scc_
+ the stack of lexically enclosing SCC
annotations on top of the special CAF
cost-centre. Otherwise, costs are attributed to the stack of
- lexically-enclosing _scc_ annotations,
+ lexically-enclosing SCC annotations,
appended to the cost-centre stack in effect at the
call site of the current top-level
definitionThe call-site is just the place
@@ -358,7 +365,7 @@ x = nfib 25
You can view the time and allocation profiling graph of your
program graphically, using ghcprof. This is a
- new tool with GHC 4.07, and will eventually be the de-facto
+ new tool with GHC 4.08, and will eventually be the de-facto
standard way of viewing GHC profiles.To run ghcprof, you need
@@ -587,6 +594,75 @@ $ ghcprof <prog>.prof
+ :
+
+ heap profile filtering options
+
+ It's often useful to select just some subset of the
+ heap when profiling. To do this, the following filters are
+ available. You may use multiple filters, in which case a
+ closure has to satisfy all filters to appear in the final
+ profile. Filtering criterion are independent of what it is
+ you ask to see. So, for example, you can specify a profile
+ by closure description (-hD) but ask to
+ filter closures by producer module (-hm{...}).
+
+
+ Available filters are:
+
+
+
+
+ :
+
+ Restrict to one of the specified cost centers.
+ Since GHC deals in cost center stacks, the specified
+ cost centers pertain to the top stack element. For
+ example, -hc{Wurble,Burble} selects
+ all cost center stacks whose top element is
+ Wurble or
+ Burble.
+
+
+
+
+
+ :
+
+ Restrict to closures produced by functions in
+ one of the specified modules.
+
+
+
+
+
+ :
+
+ Restrict to closures whose description-string is
+ one of the specified descriptions. Description
+ strings are pretty arcane. An easy way to find
+ plausible strings to specify is to first do a
+ -hD profile and then inspect the
+ description-strings which appear in the resulting profile.
+
+
+
+
+
+ :
+
+ Restrict to closures having one of the specified
+ types.
+
+
+
+
+
+
+
+
+ :
@@ -598,6 +674,18 @@ $ ghcprof <prog>.prof
+
+
+ RTS
+ option
+
+ This option makes use of the extra information
+ maintained by the cost-centre-stack profiler to provide
+ useful information about the location of runtime errors.
+ See .
+
+
+