From ad6ee9e85723a742fe76e6903a63f2796136fe98 Mon Sep 17 00:00:00 2001 From: Araq <rumpf_a@web.de> Date: Sat, 15 Sep 2012 01:27:53 +0200 Subject: profiler documentation --- doc/estp.txt | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/tools.txt | 3 + 2 files changed, 183 insertions(+) create mode 100644 doc/estp.txt (limited to 'doc') diff --git a/doc/estp.txt b/doc/estp.txt new file mode 100644 index 000000000..a3cbee516 --- /dev/null +++ b/doc/estp.txt @@ -0,0 +1,180 @@ +============================================ + Embedded Stack Trace Profiler User Guide +============================================ + +:Author: Andreas Rumpf +:Version: |nimrodversion| + + +Nimrod comes with a platform independent profiler - +the `Embedded Stack Trace Profiler`:idx: (`ESTP`:idx:). The profiler +is *embedded* into your executable. To activate the profiler you need to do: + +* compile your program with the ``--profiler:on --stackTrace:on`` command + line options +* import the ``nimprof`` module +* run your program as usual. + +You can in fact look at ``nimprof``'s source code to see how to implement +your own profiler. + +The setting ``--profiler:on`` defines the conditional symbol ``profiler``. + +After your program has finished the profiler will create a +file ``profile_resultsX.txt``(where ``X`` is a previously unused number) +containing the profiling results. + +Since the profiler works by examining stack traces, it's essential that +the option ``--stackTrace:on`` is active! Unfortunately this means that a +profiling build is much slower than a release build. + + +Example results file +==================== + +The results file lists stack traces ordered by significance. + +The following example file has been generated by profiling the Nimrod compiler +itself: It shows that in total 4.1% of the runtime has been spent +in ``crcFromRope`` or its children. + +In general the stack traces show you immediately where the problem is because +the trace acts like an explanation; in traditional profilers you can only find +expensive leaf functions easily but the *reason* why they are invoked +often remains mysterious. + +:: + total executions of each stack trace: + Entry: 0/3391 Calls: 84/4160 = 2.0% [sum: 84; 84/4160 = 2.0%] + newCrcFromRopeAux + crcFromRope + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%] + updateCrc32 + newCrcFromRopeAux + crcFromRope + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%] + updateCrc32 + updateCrc32 + newCrcFromRopeAux + crcFromRope + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%] + crcFromFile + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%] + updateCrc32 + crcFromFile + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%] + pop + newCrcFromRopeAux + crcFromRope + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + nimrod + Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%] + doOperation + forAllChildrenAux + pop + newCrcFromRopeAux + crcFromRope + writeRopeIfNotEqual + shouldRecompile + writeModule + myClose + closePasses + processModule + CompileModule + CompileProject + CommandCompileToC + MainCommand + HandleCmdLine + ... + nimrod + Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%] + Contains + isAccessible + interiorAllocatedPtr + gcMark + markStackAndRegisters + collectCTBody + collectCT + rawNewObj + newObj + newNode + copyTree + matchesAux + matches + resolveOverloads + semOverloadedCall + semOverloadedCallAnalyseEffects + ... + CommandCompileToC + MainCommand + HandleCmdLine diff --git a/doc/tools.txt b/doc/tools.txt index bd79745f6..ae739e778 100755 --- a/doc/tools.txt +++ b/doc/tools.txt @@ -15,3 +15,6 @@ The standard distribution ships with the following tools: - | `endb <endb.html>`_ | Nimrod's slow platform independent embedded debugger. + +- | `estp <estp.html>`_ + | Nimrod's slow platform independent embedded stack trace profiler. -- cgit 1.4.1-2-gfad0