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 + entries The 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 %time The 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 %alloc The 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 definition The 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 . + + +