============================================
  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_results.txt`` 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 5.4% 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