mirror of
https://github.com/nim-lang/Nim.git
synced 2025-12-28 17:04:41 +00:00
200 lines
10 KiB
HTML
200 lines
10 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!-- This file is generated by Nim. -->
|
|
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Embedded Stack Trace Profiler (ESTP) User Guide</title>
|
|
|
|
<!-- Google fonts -->
|
|
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
|
|
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
|
|
|
<!-- Favicon -->
|
|
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
|
|
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
|
|
|
|
<!-- CSS -->
|
|
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
|
|
|
|
<!-- JS -->
|
|
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
|
|
</head>
|
|
<body>
|
|
<div class="document" id="documentId">
|
|
<div class="container">
|
|
<h1 class="title">Embedded Stack Trace Profiler (ESTP) User Guide</h1>
|
|
<table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Andreas Rumpf</td></tr>
|
|
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
|
|
</tbody></table><p>Nim comes with a platform independent profiler - the Embedded Stack Trace Profiler (ESTP). The profiler is <em>embedded</em> into your executable. To activate the profiler you need to do:</p>
|
|
<ul class="simple"><li>compile your program with the <tt class="docutils literal"><span class="pre option">--profiler:on --stackTrace:on</span></tt> command line options</li>
|
|
<li>import the <tt class="docutils literal"><span class="pre"><span class="Identifier">nimprof</span></span></tt> module</li>
|
|
<li>run your program as usual.</li>
|
|
</ul>
|
|
<p>You can in fact look at <tt class="docutils literal"><span class="pre"><span class="Identifier">nimprof</span></span></tt>'s source code to see how to implement your own profiler.</p>
|
|
<p>The setting <tt class="docutils literal"><span class="pre option">--profiler:on</span></tt> defines the conditional symbol <tt class="docutils literal"><span class="pre"><span class="Identifier">profiler</span></span></tt>. You can use <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span> <span class="Identifier">compileOption</span><span class="Punctuation">(</span><span class="StringLit">"profiler"</span><span class="Punctuation">)</span></span></tt> to make the switch seamless. If <tt class="docutils literal"><span class="pre option">profiler</span></tt> is <tt class="docutils literal"><span class="pre option">off</span></tt>, your program runs normally. Otherwise your program is profiled.</p>
|
|
<p><pre class="listing"><span class="Keyword">when</span> <span class="Identifier">compileOption</span><span class="Punctuation">(</span><span class="StringLit">"profiler"</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
|
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">nimprof</span></pre></p>
|
|
<p>After your program has finished the profiler will create a file <tt class="docutils literal"><span class="pre">profile_results.txt</span></tt> containing the profiling results.</p>
|
|
<p>Since the profiler works by examining stack traces, it's essential that the option <tt class="docutils literal"><span class="pre option">--stackTrace:on</span></tt> is active! Unfortunately this means that a profiling build is much slower than a release build.</p>
|
|
|
|
<h1 id="memory-profiler">Memory profiler</h1><p>You can also use ESTP as a memory profiler to see which stack traces allocate the most memory and thus create the most GC pressure. It may also help to find memory leaks. To activate the memory profiler you need to do:</p>
|
|
<ul class="simple"><li>compile your program with the <tt class="docutils literal"><span class="pre option">--profiler:off --stackTrace:on -d:memProfiler</span></tt> command line options. Yes it's <tt class="docutils literal"><span class="pre option">--profiler:off</span></tt>.</li>
|
|
<li>import the <tt class="docutils literal"><span class="pre"><span class="Identifier">nimprof</span></span></tt> module</li>
|
|
<li>run your program as usual.</li>
|
|
</ul>
|
|
<p>Define the symbol <tt class="docutils literal"><span class="pre"><span class="Identifier">ignoreAllocationSize</span></span></tt> so that only the number of allocations is counted and the sizes of the memory allocations do not matter.</p>
|
|
|
|
<h1 id="example-results-file">Example results file</h1><p>The results file lists stack traces ordered by significance.</p>
|
|
<p>The following example file has been generated by profiling the Nim compiler itself: It shows that in total 5.4% of the runtime has been spent in <tt class="docutils literal"><span class="pre"><span class="Identifier">crcFromRope</span></span></tt> or its children.</p>
|
|
<p>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 <em>reason</em> why they are invoked often remains mysterious.</p>
|
|
<pre>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
|
|
nim
|
|
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
|
|
nim
|
|
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
|
|
nim
|
|
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
|
|
nim
|
|
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
|
|
nim
|
|
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
|
|
nim
|
|
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
|
|
...
|
|
nim
|
|
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</pre>
|
|
|
|
|
|
|
|
<div class="twelve-columns footer">
|
|
<span class="nim-sprite"></span>
|
|
<br>
|
|
<small style="color: var(--hint);">Made with Nim. Generated: 2025-12-28 15:54:16 UTC</small>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
|
|
|
|
</body>
|
|
</html>
|