levovix
/
Nim
mirror of https://github.com/nim-lang/Nim


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200
							<?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">&quot;profiler&quot;</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">&quot;profiler&quot;</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-03-15 14:12:49 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>