levovix
/
Nim
огледало от https://github.com/nim-lang/Nim


			
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
							<?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>doc/refc</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">doc/refc</h1>
      
<h1 id="tweaking-the-refc-gc">Tweaking the refc GC</h1>
<h2 id="cycle-collector">Cycle collector</h2><p>The cycle collector can be en-/disabled independently from the other parts of the garbage collector with <tt class="docutils literal"><span class="pre">GC_enableMarkAndSweep</span></tt> and <tt class="docutils literal"><span class="pre">GC_disableMarkAndSweep</span></tt>.</p>

<h2 id="soft-realminustime-support">Soft real-time support</h2><p>To enable real-time support, the symbol <span id="userealtimegc_1">useRealtimeGC</span> needs to be defined via <tt class="docutils literal"><span class="pre option">--define:useRealtimeGC</span></tt> (you can put this into your config file as well). With this switch the garbage collector supports the following operations:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">GC_setMaxPause</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">maxPauseInUs</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Keyword">proc</span> <span class="Identifier">GC_step</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">us</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">strongAdvice</span> <span class="Operator">=</span> <span class="Identifier">false</span><span class="Punctuation">,</span> <span class="Identifier">stackSize</span> <span class="Operator">=</span> <span class="Operator">-</span><span class="DecNumber">1</span><span class="Punctuation">)</span></pre></p>
<p>The unit of the parameters <tt class="docutils literal"><span class="pre">maxPauseInUs</span></tt> and <tt class="docutils literal"><span class="pre">us</span></tt> is microseconds.</p>
<p>These two procs are the two modus operandi of the real-time garbage collector:</p>
<ol class="simple"><li><p>GC_SetMaxPause Mode</p>
<p>You can call <tt class="docutils literal"><span class="pre">GC_SetMaxPause</span></tt> at program startup and then each triggered garbage collector run tries to not take longer than <tt class="docutils literal"><span class="pre">maxPause</span></tt> time. However, it is possible (and common) that the work is nevertheless not evenly distributed as each call to <tt class="docutils literal"><span class="pre">new</span></tt> can trigger the garbage collector and thus take  <tt class="docutils literal"><span class="pre">maxPause</span></tt> time.</p>
</li>
<li><p>GC_step Mode</p>
<p>This allows the garbage collector to perform some work for up to <tt class="docutils literal"><span class="pre">us</span></tt> time. This is useful to call in the main loop to ensure the garbage collector can do its work. To bind all garbage collector activity to a <tt class="docutils literal"><span class="pre">GC_step</span></tt> call, deactivate the garbage collector with <tt class="docutils literal"><span class="pre">GC_disable</span></tt> at program startup. If <tt class="docutils literal"><span class="pre">strongAdvice</span></tt> is set to <tt class="docutils literal"><span class="pre">true</span></tt>, then the garbage collector will be forced to perform the collection cycle. Otherwise, the garbage collector may decide not to do anything, if there is not much garbage to collect. You may also specify the current stack size via <tt class="docutils literal"><span class="pre">stackSize</span></tt> parameter. It can improve performance when you know that there are no unique Nim references below a certain point on the stack. Make sure the size you specify is greater than the potential worst-case size.</p>
<p>It can improve performance when you know that there are no unique Nim references below a certain point on the stack. Make sure the size you specify is greater than the potential worst-case size.</p>
</li>
</ol>
<p>These procs provide a &quot;best effort&quot; real-time guarantee; in particular the cycle collector is not aware of deadlines. Deactivate it to get more predictable real-time behaviour. Tests show that a 1ms max pause time will be met in almost all cases on modern CPUs (with the cycle collector disabled).</p>

<h2 id="time-measurement-with-garbage-collectors">Time measurement with garbage collectors</h2><p>The garbage collectors' way of measuring time uses (see <tt class="docutils literal"><span class="pre">lib/system/timers.nim</span></tt> for the implementation):</p>
<ol class="simple"><li><tt class="docutils literal"><span class="pre">QueryPerformanceCounter</span></tt> and <tt class="docutils literal"><span class="pre">QueryPerformanceFrequency</span></tt> on Windows.</li>
<li><tt class="docutils literal"><span class="pre">mach_absolute_time</span></tt> on Mac OS X.</li>
<li><tt class="docutils literal"><span class="pre">gettimeofday</span></tt> on Posix systems.</li>
</ol>
<p>As such it supports a resolution of nanoseconds internally; however, the API uses microseconds for convenience.</p>
<p>Define the symbol <tt class="docutils literal"><span class="pre">reportMissedDeadlines</span></tt> to make the garbage collector output whenever it missed a deadline. The reporting will be enhanced and supported by the API in later versions of the collector.</p>

<h2 id="tweaking-the-garbage-collector">Tweaking the garbage collector</h2><p>The collector checks whether there is still time left for its work after every <tt class="docutils literal"><span class="pre">workPackage</span></tt>'th iteration. This is currently set to 100 which means that up to 100 objects are traversed and freed before it checks again. Thus <tt class="docutils literal"><span class="pre">workPackage</span></tt> affects the timing granularity and may need to be tweaked in highly specialized environments or for older hardware.</p>

<h2 id="thread-coordination">Thread coordination</h2><p>When the <tt class="docutils literal"><span class="pre">NimMain()</span></tt> function is called Nim initializes the garbage collector to the current thread, which is usually the main thread of your application. If your C code later spawns a different thread and calls Nim code, the garbage collector will fail to work properly and you will crash.</p>
<p>As long as you don't use the threadvar emulation Nim uses native thread variables, of which you get a fresh version whenever you create a thread. You can then attach a GC to this thread via</p>
<p><pre class="listing"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">setupForeignThreadGc</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>It is <strong>not</strong> safe to disable the garbage collector and enable it after the call from your background thread even if the code you are calling is short lived.</p>
<p>Before the thread exits, you should tear down the thread's GC to prevent memory leaks by calling</p>
<p><pre class="listing"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">tearDownForeignThreadGc</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>

<h1 id="keeping-track-of-memory">Keeping track of memory</h1><p>If you need to pass around memory allocated by Nim to C, you can use the procs <tt class="docutils literal"><span class="pre">GC_ref</span></tt> and <tt class="docutils literal"><span class="pre">GC_unref</span></tt> to mark objects as referenced to avoid them being freed by the garbage collector. Other useful procs from <a class="reference external" href="system.html">system</a> you can use to keep track of memory are:</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre">getTotalMem()</span></tt> Returns the amount of total memory managed by the garbage collector.</li>
<li><tt class="docutils literal"><span class="pre">getOccupiedMem()</span></tt> Bytes reserved by the garbage collector and used by objects.</li>
<li><tt class="docutils literal"><span class="pre">getFreeMem()</span></tt> Bytes reserved by the garbage collector and not in use.</li>
<li><tt class="docutils literal"><span class="pre">GC_getStatistics()</span></tt> Garbage collector statistics as a human-readable string.</li>
</ul>
<p>These numbers are usually only for the running thread, not for the whole heap, with the exception of <tt class="docutils literal"><span class="pre option">--mm:boehm</span></tt> and <tt class="docutils literal"><span class="pre option">--mm:go</span></tt>.</p>
<p>In addition to <tt class="docutils literal"><span class="pre">GC_ref</span></tt> and <tt class="docutils literal"><span class="pre">GC_unref</span></tt> you can avoid the garbage collector by manually allocating memory with procs like <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">alloc0</span></tt>, <tt class="docutils literal"><span class="pre">allocShared</span></tt>, <tt class="docutils literal"><span class="pre">allocShared0</span></tt> or <tt class="docutils literal"><span class="pre">allocCStringArray</span></tt>. The garbage collector won't try to free them, you need to call their respective <em>dealloc</em> pairs (<tt class="docutils literal"><span class="pre">dealloc</span></tt>, <tt class="docutils literal"><span class="pre">deallocShared</span></tt>, <tt class="docutils literal"><span class="pre">deallocCStringArray</span></tt>, etc) when you are done with them or they will leak.</p>

<h1 id="heap-dump">Heap dump</h1><p>The heap dump feature is still in its infancy, but it already proved useful for us, so it might be useful for you. To get a heap dump, compile with <tt class="docutils literal"><span class="pre option">-d:nimTypeNames</span></tt> and call <tt class="docutils literal"><span class="pre">dumpNumberOfInstances</span></tt> at a strategic place in your program. This produces a list of the used types in your program and for every type the total amount of object instances for this type as well as the total amount of bytes these instances take up.</p>
<p>The numbers count the number of objects in all garbage collector heaps, they refer to all running threads, not only to the current thread. (The current thread would be the thread that calls <tt class="docutils literal"><span class="pre">dumpNumberOfInstances</span></tt>.) This might change in later versions. </p>


      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-02-06 22:27:32 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>