levovix
/
Nim
spegling av https://github.com/nim-lang/Nim


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538
							<?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>Nim Destructors and Move Semantics</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">Nim Destructors and Move Semantics</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="about-this-document_toc" href="#about-this-document">About this document</a></li>
<li><a class="reference" id="motivating-example_toc" href="#motivating-example">Motivating example</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks_toc" href="#lifetimeminustracking-hooks">Lifetime-tracking hooks</a></li>
<ul class="simple"><li><a class="reference" id="lifetimeminustracking-hooks-nimeqdestroy-hook_toc" href="#lifetimeminustracking-hooks-nimeqdestroy-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> hook</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks-nimeqwasmoved-hook_toc" href="#lifetimeminustracking-hooks-nimeqwasmoved-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt> hook</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks-nimeqsink-hook_toc" href="#lifetimeminustracking-hooks-nimeqsink-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> hook</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks-nimeqcopy-hook_toc" href="#lifetimeminustracking-hooks-nimeqcopy-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> hook</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks-nimeqtrace-hook_toc" href="#lifetimeminustracking-hooks-nimeqtrace-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> hook</a></li>
<li><a class="reference" id="lifetimeminustracking-hooks-nimeqdup-hook_toc" href="#lifetimeminustracking-hooks-nimeqdup-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span></span></tt> hook</a></li>
</ul><li><a class="reference" id="move-semantics_toc" href="#move-semantics">Move semantics</a></li>
<li><a class="reference" id="swap_toc" href="#swap">Swap</a></li>
<li><a class="reference" id="sink-parameters_toc" href="#sink-parameters">Sink parameters</a></li>
<li><a class="reference" id="sink-parameter-inference_toc" href="#sink-parameter-inference">Sink parameter inference</a></li>
<li><a class="reference" id="rewrite-rules_toc" href="#rewrite-rules">Rewrite rules</a></li>
<li><a class="reference" id="object-and-array-construction_toc" href="#object-and-array-construction">Object and array construction</a></li>
<li><a class="reference" id="destructor-removal_toc" href="#destructor-removal">Destructor removal</a></li>
<li><a class="reference" id="self-assignments_toc" href="#self-assignments">Self assignments</a></li>
<li><a class="reference" id="lent-type_toc" href="#lent-type">Lent type</a></li>
<li><a class="reference" id="the-cursor-pragma_toc" href="#the-cursor-pragma">The cursor pragma</a></li>
<li><a class="reference" id="cursor-inference-slash-copy-elision_toc" href="#cursor-inference-slash-copy-elision">Cursor inference / copy elision</a></li>
<li><a class="reference" id="hook-lifting_toc" href="#hook-lifting">Hook lifting</a></li>
<li><a class="reference" id="hook-generation_toc" href="#hook-generation">Hook generation</a></li>
<li><a class="reference" id="nodestroy-pragma_toc" href="#nodestroy-pragma">nodestroy pragma</a></li>
<li><a class="reference" id="copy-on-write_toc" href="#copy-on-write">Copy on write</a></li>

</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/destructors.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/destructors.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Authors:</th><td>Andreas Rumpf</td></tr>
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
</tbody></table>
<h1><a class="toc-backref" id="about-this-document" href="#about-this-document">About this document</a></h1><p>This document describes the ARC/ORC Nim runtime which does not use classical GC algorithms anymore but is based on destructors and move semantics. The advantages are that Nim programs become oblivious to the involved heap sizes and programs are easier to write to make effective use of multi-core machines. As a nice bonus, files and sockets and the like can be written not to require manual <tt class="docutils literal"><span class="pre"><span class="Identifier">close</span></span></tt> calls anymore.</p>
<p>This document aims to be a precise specification about how move semantics and destructors work in Nim.</p>

<h1><a class="toc-backref" id="motivating-example" href="#motivating-example">Motivating example</a></h1><p>With the language mechanisms described here, a custom seq could be written as:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">myseq</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">len</span><span class="Punctuation">,</span> <span class="Identifier">cap</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">UncheckedArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
    <span class="Identifier">dealloc</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Keyword">nil</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">trace</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">env</span><span class="Punctuation">:</span> <span class="Identifier">pointer</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># `=trace` allows the cycle collector `--mm:orc`</span>
  <span class="Comment"># to understand how to trace the object graph.</span>
  <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">trace</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">env</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">copy</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># do nothing for self-assignments:</span>
  <span class="Keyword">if</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">==</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Keyword">return</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>
  <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">len</span>
  <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">cap</span>
  <span class="Keyword">if</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">alloc</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">*</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span>
      <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">dup</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nodestroy</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># an optimized version of `=wasMoved(tmp); `=copy(tmp, src)`</span>
  <span class="Comment"># usually present if a custom `=copy` hook is overridden</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">len</span><span class="Punctuation">:</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">,</span> <span class="Identifier">cap</span><span class="Punctuation">:</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">cap</span><span class="Punctuation">,</span> <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Keyword">nil</span><span class="Punctuation">)</span>
  <span class="Keyword">if</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">alloc</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">*</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span>
      <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">dup</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># move assignment, optional.</span>
  <span class="Comment"># Compiler is using `=destroy` and `copyMem` when not provided</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>
  <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">len</span>
  <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">cap</span>
  <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">data</span>

<span class="Keyword">proc</span> <span class="Identifier">add</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">&gt;=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">cap</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">=</span> <span class="Identifier">max</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">+</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">*</span> <span class="DecNumber">2</span><span class="Punctuation">)</span>
    <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">realloc</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">*</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">y</span>
  <span class="Identifier">inc</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">Natural</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">lent</span> <span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Identifier">assert</span> <span class="Identifier">i</span> <span class="Operator">&lt;</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">Natural</span><span class="Punctuation">;</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">assert</span> <span class="Identifier">i</span> <span class="Operator">&lt;</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">y</span>

<span class="Keyword">proc</span> <span class="Identifier">createSeq</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">elems</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span>
    <span class="Identifier">len</span><span class="Punctuation">:</span> <span class="Identifier">elems</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">,</span>
    <span class="Identifier">cap</span><span class="Punctuation">:</span> <span class="Identifier">elems</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">,</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">alloc</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">cap</span> <span class="Operator">*</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span> <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">elems</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">len</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">myseq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span></pre></p>

<h1><a class="toc-backref" id="lifetimeminustracking-hooks" href="#lifetimeminustracking-hooks">Lifetime-tracking hooks</a></h1><p>The memory management for Nim's standard <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">seq</span></span></tt> types as well as other standard collections is performed via so-called &quot;Lifetime-tracking hooks&quot;, which are particular <a class="reference external" href=" manual.html#procedures-type-bound-operators">type bound operators</a>.</p>
<p>There are 6 different hooks for each (generic or concrete) object type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> (<tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> can also be a <tt class="docutils literal"><span class="pre"><span class="Keyword">distinct</span></span></tt> type) that are called implicitly by the compiler.</p>
<p>(Note: The word &quot;hook&quot; here does not imply any kind of dynamic binding or runtime indirections, the implicit calls are statically bound and potentially inlined.)</p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqdestroy-hook" href="#lifetimeminustracking-hooks-nimeqdestroy-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> hook</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> hook frees the object's associated memory and releases other associated resources. Variables are destroyed via this hook when they go out of scope or when the routine they were declared in is about to return.</p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> hook is allowed to have a parameter of a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> type. Taking a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> type is deprecated. The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span></pre></p>
<p>The general pattern in <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> looks like:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># first check if 'x' was moved to somewhere else:</span>
  <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Identifier">freeResource</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">field</span><span class="Punctuation">)</span></pre></p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> is implicitly annotated with <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>; a destructor should not raise exceptions. For backwards compatibility the compiler produces a warning for a <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> that does raise.</p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> can explicitly list the exceptions it can raise, if any, but this of little utility as a raising destructor is implementation defined behavior. Later versions of the language specification might cover this case precisely.</p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqwasmoved-hook" href="#lifetimeminustracking-hooks-nimeqwasmoved-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt> hook</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt> hook sets the object to a state that signifies to the destructor there is nothing to destroy.</p>
<p>The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">)</span></pre></p>
<p>Usually some pointer field inside the object is set to <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="Keyword">nil</span></pre></p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqsink-hook" href="#lifetimeminustracking-hooks-nimeqsink-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> hook</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> hook moves an object around, the resources are stolen from the source and passed to the destination. It is ensured that the source's destructor does not free the resources afterward by setting the object to its default value (the value the object's state started in). Setting an object <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> back to its default value is written as <tt class="docutils literal"><span class="pre"><span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>. When not provided the compiler is using a combination of <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">copyMem</span></span></tt> instead. This is efficient hence users rarely need to implement their own <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> operator, it is enough to provide <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt>, the compiler will take care of the rest.</p>
<p>The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">source</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span></pre></p>
<p>The general pattern in <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> looks like:</p>
<p><pre class="listing">
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">source</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span>
  <span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span>
  <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="Identifier">source</span><span class="Operator">.</span><span class="Identifier">field</span></pre></p>
<p><strong>Note</strong>: <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> does not need to check for self-assignments. How self-assignments are handled is explained later in this document.</p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqcopy-hook" href="#lifetimeminustracking-hooks-nimeqcopy-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> hook</a></h2><p>The ordinary assignment in Nim conceptually copies the values. The <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> hook is called for assignments that couldn't be transformed into <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> operations.</p>
<p>The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">copy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">source</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span></pre></p>
<p>The general pattern in <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> looks like:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">copy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">source</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># protect against self-assignments:</span>
  <span class="Keyword">if</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">!=</span> <span class="Identifier">source</span><span class="Operator">.</span><span class="Identifier">field</span><span class="Punctuation">:</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span>
    <span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span>
    <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="Identifier">duplicateResource</span><span class="Punctuation">(</span><span class="Identifier">source</span><span class="Operator">.</span><span class="Identifier">field</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> proc can be marked with the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">error</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma. Then any assignment that otherwise would lead to a copy is prevented at compile-time. This looks like:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">copy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">source</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">error</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>but a custom error message (e.g., <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">error</span><span class="Punctuation">:</span> <span class="StringLit">&quot;custom error&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt>) will not be emitted by the compiler. Notice that there is no <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> before the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">error</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma.</p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqtrace-hook" href="#lifetimeminustracking-hooks-nimeqtrace-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> hook</a></h2><p>A custom <strong>container</strong> type can support Nim's cycle collector <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">orc</span></span></tt> via the <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> hook. If the container does not implement <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt>, cyclic data structures which are constructed with the help of the container might leak memory or resources, but memory safety is not compromised.</p>
<p>The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">trace</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">env</span><span class="Punctuation">:</span> <span class="Identifier">pointer</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">env</span></span></tt> is used by ORC to keep track of its internal state, it should be passed around to calls of the built-in <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> operation.</p>
<p>Usually there will only be a need for a custom <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> when a custom <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> that deallocates manually allocated resources is also used, and then only when there is a chance of cyclic references from items within the manually allocated resources when it is desired that <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">orc</span></span></tt> is able to break and collect these cyclic referenced resources. Currently however, there is a mutual use problem in that whichever of <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> is used first will automatically create a version of the other which will then conflict with the creation of the second of the pair. The workaround for this problem is to forward declare the second of the &quot;hooks&quot; to prevent the automatic creation.</p>
<p>The general pattern in using <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt> with <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> looks like:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Test</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">Natural</span>
    <span class="Identifier">arr</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">UncheckedArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Comment"># raw pointer field</span>

<span class="Keyword">proc</span> <span class="Identifier">makeTest</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">Natural</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Test</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Comment"># custom allocation...</span>
  <span class="Identifier">Test</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">size</span><span class="Punctuation">,</span> <span class="Identifier">arr</span><span class="Punctuation">:</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Keyword">ptr</span> <span class="Identifier">UncheckedArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">alloc0</span><span class="Punctuation">(</span><span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">*</span> <span class="Identifier">size</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>


<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Identifier">Test</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">arr</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="DecNumber">0</span> <span class="Operator">..&lt;</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">arr</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span>
    <span class="Identifier">dealloc</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">arr</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">trace</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Test</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">env</span><span class="Punctuation">:</span> <span class="Identifier">pointer</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">arr</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Comment"># trace the `T`'s which may be cyclic</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="DecNumber">0</span> <span class="Operator">..&lt;</span> <span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">trace</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Operator">.</span><span class="Identifier">arr</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">env</span><span class="Punctuation">)</span>

<span class="Comment"># following may be other custom &quot;hooks&quot; as required...</span></pre></p>
<p><strong>Note</strong>: The <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt> hooks (which are only used by <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">orc</span></span></tt>) are currently more experimental and less refined than the other hooks.</p>

<h2><a class="toc-backref" id="lifetimeminustracking-hooks-nimeqdup-hook" href="#lifetimeminustracking-hooks-nimeqdup-hook"><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span></span></tt> hook</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span></span></tt> hook duplicates an object. <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> can be regarded as an optimization replacing a <tt class="docutils literal"><span class="pre"><span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Operator">=</span><span class="Identifier">copy</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> operation.</p>
<p>The prototype of this hook for a type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> needs to be:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">dup</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">T</span></pre></p>
<p>The general pattern in implementing <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span></span></tt> looks like:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Keyword">Ref</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">T</span>
    <span class="Identifier">rc</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">dup</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">Ref</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">Ref</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span>
  <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">rc</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Identifier">inc</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">rc</span><span class="Punctuation">[</span><span class="Punctuation">]</span></pre></p>

<h1><a class="toc-backref" id="move-semantics" href="#move-semantics">Move semantics</a></h1><p>A &quot;move&quot; can be regarded as an optimized copy operation. If the source of the copy operation is not used afterward, the copy can be replaced by a move. This document uses the notation <tt class="docutils literal"><span class="pre"><span class="Identifier">lastReadOf</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> to describe that <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> is not used afterward. This property is computed by a static control flow analysis but can also be enforced by using <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">move</span></span></tt> explicitly.</p>
<p>One can query if the analysis is able to perform a move with <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">ensureMove</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Identifier">move</span></span></tt> enforces a move operation and calls <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt> whereas <tt class="docutils literal"><span class="pre"><span class="Identifier">ensureMove</span></span></tt> is an annotation that implies no runtime operation. An <tt class="docutils literal"><span class="pre"><span class="Identifier">ensureMove</span></span></tt> annotation leads to a static error if the compiler cannot prove that a move would be safe.</p>
<p>For example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Identifier">normalParam</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">sinkParam</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>
  <span class="Comment"># valid:</span>
  <span class="Keyword">let</span> <span class="Identifier">valid</span> <span class="Operator">=</span> <span class="Identifier">ensureMove</span> <span class="Identifier">x</span>
  <span class="Comment"># invalid:</span>
  <span class="Keyword">let</span> <span class="Identifier">invalid</span> <span class="Operator">=</span> <span class="Identifier">ensureMove</span> <span class="Identifier">normalParam</span>
  <span class="Comment"># valid:</span>
  <span class="Keyword">let</span> <span class="Identifier">alsoValid</span> <span class="Operator">=</span> <span class="Identifier">ensureMove</span> <span class="Identifier">sinkParam</span></pre></p>

<h1><a class="toc-backref" id="swap" href="#swap">Swap</a></h1><p>The need to check for self-assignments and also the need to destroy previous objects inside <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> is a strong indicator to treat <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">swap</span></span></tt> as a builtin primitive of its own that simply swaps every field in the involved objects via <tt class="docutils literal"><span class="pre"><span class="Identifier">copyMem</span></span></tt> or a comparable mechanism. In other words, <tt class="docutils literal"><span class="pre"><span class="Identifier">swap</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt> is <strong>not</strong> implemented as <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span> <span class="Identifier">tmp</span> <span class="Operator">=</span> <span class="Identifier">move</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">move</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">move</span><span class="Punctuation">(</span><span class="Identifier">tmp</span><span class="Punctuation">)</span></span></tt>.</p>
<p>This has further consequences:</p>
<ul class="simple"><li>Objects that contain pointers that point to the same object are not supported by Nim's model. Otherwise swapped objects would end up in an inconsistent state.</li>
<li>Seqs can use <tt class="docutils literal"><span class="pre"><span class="Identifier">realloc</span></span></tt> in the implementation.</li>
</ul>

<h1><a class="toc-backref" id="sink-parameters" href="#sink-parameters">Sink parameters</a></h1><p>To move a variable into a collection usually <tt class="docutils literal"><span class="pre"><span class="Identifier">sink</span></span></tt> parameters are involved. A location that is passed to a <tt class="docutils literal"><span class="pre"><span class="Identifier">sink</span></span></tt> parameter should not be used afterward. This is ensured by a static analysis over a control flow graph. If it cannot be proven to be the last usage of the location, a copy is done instead and this copy is then passed to the sink parameter.</p>
<p>A sink parameter <em>may</em> be consumed once in the proc's body but doesn't have to be consumed at all. The reason for this is that signatures like <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">put</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Table</span><span class="Punctuation">;</span> <span class="Identifier">k</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">Value</span><span class="Punctuation">)</span></span></tt> should be possible without any further overloads and <tt class="docutils literal"><span class="pre"><span class="Identifier">put</span></span></tt> might not take ownership of <tt class="docutils literal"><span class="pre"><span class="Identifier">k</span></span></tt> if <tt class="docutils literal"><span class="pre"><span class="Identifier">k</span></span></tt> already exists in the table. Sink parameters enable an affine type system, not a linear type system.</p>
<p>The employed static analysis is limited and only concerned with local variables; however, object and tuple fields are treated as separate entities:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">consume</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">Obj</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span> <span class="StringLit">&quot;no implementation&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">tup</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Identifier">Obj</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">Obj</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Identifier">consume</span> <span class="Identifier">tup</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Comment"># ok, only tup[0] was consumed, tup[1] is still alive:</span>
  <span class="Identifier">echo</span> <span class="Identifier">tup</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span></pre></p>
<p>Sometimes it is required to explicitly <tt class="docutils literal"><span class="pre"><span class="Identifier">move</span></span></tt> a value into its final position:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">dest</span><span class="Punctuation">,</span> <span class="Identifier">src</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="DecNumber">10</span><span class="Punctuation">,</span> <span class="Identifier">string</span><span class="Punctuation">]</span>
  <span class="Comment"># ...</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">dest</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">dest</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">move</span><span class="Punctuation">(</span><span class="Identifier">src</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>An implementation is allowed, but not required to implement even more move optimizations (and the current implementation does not).</p>

<h1><a class="toc-backref" id="sink-parameter-inference" href="#sink-parameter-inference">Sink parameter inference</a></h1><p>The current implementation can do a limited form of sink parameter inference. But it has to be enabled via <tt class="docutils literal"><span class="pre option">--sinkInference:on</span></tt>, either on the command line or via a <tt class="docutils literal"><span class="pre"><span class="Identifier">push</span></span></tt> pragma.</p>
<p>To enable it for a section of code, one can use <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">sinkInference</span><span class="Punctuation">:</span> <span class="Identifier">on</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> ... <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt>.</p>
<p>The <span id="dotnosinks_1">.nosinks</span> pragma can be used to disable this inference for a single routine:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">addX</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">child</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nosinks</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">child</span></pre></p>
<p>The details of the inference algorithm are currently undocumented.</p>

<h1><a class="toc-backref" id="rewrite-rules" href="#rewrite-rules">Rewrite rules</a></h1><p><strong>Note</strong>: There are two different allowed implementation strategies:</p>
<ol class="simple"><li>The produced <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> section can be a single section that is wrapped around the complete routine body.</li>
<li>The produced <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> section is wrapped around the enclosing scope.</li>
</ol>
<p>The current implementation follows strategy (2). This means that resources are destroyed at the scope exit.</p>
<pre>var x: T; stmts
---------------             (destroy-var)
var x: T; try stmts
finally: `=destroy`(x)


g(f(...))
------------------------    (nested-function-call)
g(let tmp;
bitwiseCopy tmp, f(...);
tmp)
finally: `=destroy`(tmp)


x = f(...)
------------------------    (function-sink)
`=sink`(x, f(...))


x = lastReadOf z
------------------          (move-optimization)
`=sink`(x, z)
`=wasMoved`(z)


v = v
------------------   (self-assignment-removal)
discard &quot;nop&quot;


x = y
------------------          (copy)
`=copy`(x, y)


f_sink(g())
-----------------------     (call-to-sink)
f_sink(g())


f_sink(notLastReadOf y)
--------------------------     (copy-to-sink)
(let tmp = `=dup`(y);
f_sink(tmp))


f_sink(lastReadOf y)
-----------------------     (move-to-sink)
f_sink(y)
`=wasMoved`(y)</pre>

<h1><a class="toc-backref" id="object-and-array-construction" href="#object-and-array-construction">Object and array construction</a></h1><p>Object and array construction is treated as a function call where the function has <tt class="docutils literal"><span class="pre"><span class="Identifier">sink</span></span></tt> parameters.</p>

<h1><a class="toc-backref" id="destructor-removal" href="#destructor-removal">Destructor removal</a></h1><p><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> followed by a <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> operation cancel each other out. An implementation is encouraged to exploit this in order to improve efficiency and code sizes. The current implementation does perform this optimization.</p>

<h1><a class="toc-backref" id="self-assignments" href="#self-assignments">Self assignments</a></h1><p><tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> in combination with <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt> can handle self-assignments but it's subtle.</p>
<p>The simple case of <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">x</span></span></tt> cannot be turned into <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> because that would lose <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>'s value. The solution is that simple self-assignments that consist of</p>
<ul class="simple"><li>Symbols: <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">x</span></span></tt></li>
<li>Field access: <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span></span></tt></li>
<li>Array, sequence or string access with indices known at compile-time: <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span></span></tt></li>
</ul>
<p>are transformed into an empty statement that does nothing. The compiler is free to optimize further cases.</p>
<p>The complex case looks like a variant of <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">f</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>, we consider <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">select</span><span class="Punctuation">(</span><span class="Identifier">rand</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">&lt;</span> <span class="FloatNumber">0.5</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span></span></tt> here:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">select</span><span class="Punctuation">(</span><span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">;</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Comment"># moves a into result</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Comment"># moves b into result</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>
  <span class="Keyword">var</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="StringLit">&quot;xyz&quot;</span>
  <span class="Comment"># possible self-assignment:</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">select</span><span class="Punctuation">(</span><span class="Identifier">true</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span></pre></p>
<p>Is transformed into:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">select</span><span class="Punctuation">(</span><span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">;</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Keyword">if</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">)</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>
    <span class="Keyword">else</span><span class="Punctuation">:</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">,</span> <span class="StringLit">&quot;xyz&quot;</span><span class="Punctuation">)</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">select</span><span class="Punctuation">(</span><span class="Identifier">true</span><span class="Punctuation">,</span>
      <span class="Keyword">let</span> <span class="Identifier">blitTmp</span> <span class="Operator">=</span> <span class="Identifier">x</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>
      <span class="Identifier">blitTmp</span><span class="Punctuation">,</span>
      <span class="Keyword">let</span> <span class="Identifier">blitTmp</span> <span class="Operator">=</span> <span class="Identifier">y</span>
      <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span>
      <span class="Identifier">blitTmp</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Identifier">echo</span> <span class="Punctuation">[</span><span class="Identifier">x</span><span class="Punctuation">]</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>As can be manually verified, this transformation is correct for self-assignments.</p>

<h1><a class="toc-backref" id="lent-type" href="#lent-type">Lent type</a></h1><p><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">T</span><span class="Punctuation">)</span></span></tt> means that the proc <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> takes ownership of <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>. To eliminate even more creation/copy &lt;-&gt; destruction pairs, a proc's return type can be annotated as <tt class="docutils literal"><span class="pre"><span class="Identifier">lent</span> <span class="Identifier">T</span></span></tt>. This is useful for &quot;getter&quot; accessors that seek to allow an immutable view into a container.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">sink</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">lent</span></span></tt> annotations allow us to remove most (if not all) superfluous copies and destructions.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">lent</span> <span class="Identifier">T</span></span></tt> is like <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> a hidden pointer. It is proven by the compiler that the pointer does not outlive its origin. No destructor call is injected for expressions of type <tt class="docutils literal"><span class="pre"><span class="Identifier">lent</span> <span class="Identifier">T</span></span></tt> or of type <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Tree</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">kids</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Tree</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Identifier">kids</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Tree</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Tree</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">Tree</span><span class="Punctuation">(</span><span class="Identifier">kids</span><span class="Punctuation">:</span> <span class="Identifier">kids</span><span class="Punctuation">)</span>
  <span class="Comment"># converted into:</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">sink</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">kids</span><span class="Punctuation">,</span> <span class="Identifier">kids</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">wasMoved</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">kids</span><span class="Punctuation">)</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">kids</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Tree</span><span class="Punctuation">;</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">lent</span> <span class="Identifier">Tree</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">kids</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
  <span class="Comment"># borrows from 'x', this is transformed into:</span>
  <span class="Comment"># result = addr x.kids[i]</span>
  <span class="Comment"># This means 'lent' is like 'var T' a hidden pointer.</span>
  <span class="Comment"># Unlike 'var' this hidden pointer cannot be used to mutate the object.</span>

<span class="Keyword">iterator</span> <span class="Identifier">children</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">Tree</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">lent</span> <span class="Identifier">Tree</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">x</span> <span class="Keyword">in</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">kids</span><span class="Punctuation">:</span> <span class="Keyword">yield</span> <span class="Identifier">x</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Comment"># everything turned into moves:</span>
  <span class="Keyword">let</span> <span class="Identifier">t</span> <span class="Operator">=</span> <span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
  <span class="Identifier">echo</span> <span class="Identifier">t</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Comment"># accessor does not copy the element!</span></pre></p>

<h1><a class="toc-backref" id="the-cursor-pragma" href="#the-cursor-pragma">The cursor pragma</a></h1><p>Under the <tt class="docutils literal"><span class="pre option">--mm:arc|orc</span></tt> modes Nim's <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> type is implemented via the same runtime &quot;hooks&quot; and thus via reference counting. This means that cyclic structures cannot be freed immediately (<tt class="docutils literal"><span class="pre option">--mm:orc</span></tt> ships with a cycle collector). With the <tt class="docutils literal"><span class="pre"><span class="Identifier">cursor</span></span></tt> pragma one can break up cycles declaratively:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">left</span><span class="Punctuation">:</span> <span class="Identifier">Node</span> <span class="Comment"># owning ref</span>
    <span class="Identifier">right</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cursor</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">Node</span> <span class="Comment"># non-owning ref</span></pre></p>
<p>But please notice that this is not C++'s weak_ptr, it means the right field is not involved in the reference counting, it is a raw pointer without runtime checks.</p>
<p>Automatic reference counting also has the disadvantage that it introduces overhead when iterating over linked structures. The <tt class="docutils literal"><span class="pre"><span class="Identifier">cursor</span></span></tt> pragma can also be used to avoid this overhead:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">it</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cursor</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">listRoot</span>
<span class="Keyword">while</span> <span class="Identifier">it</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
  <span class="Identifier">use</span><span class="Punctuation">(</span><span class="Identifier">it</span><span class="Punctuation">)</span>
  <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">next</span></pre></p>
<p>In fact, <tt class="docutils literal"><span class="pre"><span class="Identifier">cursor</span></span></tt> more generally prevents object construction/destruction pairs and so can also be useful in other contexts. The alternative solution would be to use raw pointers (<tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt>) instead which is more cumbersome and also more dangerous for Nim's evolution: Later on, the compiler can try to prove <tt class="docutils literal"><span class="pre"><span class="Identifier">cursor</span></span></tt> pragmas to be safe, but for <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt> the compiler has to remain silent about possible problems.</p>

<h1><a class="toc-backref" id="cursor-inference-slash-copy-elision" href="#cursor-inference-slash-copy-elision">Cursor inference / copy elision</a></h1><p>The current implementation also performs <tt class="docutils literal"><span class="pre"><span class="Identifier">cursor</span></span></tt> inference. Cursor inference is a form of copy elision.</p>
<p>To see how and when we can do that, think about this question: In <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span> <span class="Operator">=</span> <span class="Identifier">src</span></span></tt> when do we really have to <em>materialize</em> the full copy? - Only if <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">src</span></span></tt> are mutated afterward. If <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span></span></tt> is a local variable that is simple to analyze. And if <tt class="docutils literal"><span class="pre"><span class="Identifier">src</span></span></tt> is a location derived from a formal parameter, we also know it is not mutated! In other words, we do a compile-time copy-on-write analysis.</p>
<p>This means that &quot;borrowed&quot; views can be written naturally and without explicit pointer indirections:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Identifier">tab</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">v</span> <span class="Operator">=</span> <span class="Identifier">tab</span><span class="Punctuation">[</span><span class="StringLit">&quot;key&quot;</span><span class="Punctuation">]</span> <span class="Comment"># inferred as cursor because 'tab' is not mutated.</span>
  <span class="Comment"># no copy into 'v', no destruction of 'v'.</span>
  <span class="Identifier">use</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">)</span>
  <span class="Identifier">useItAgain</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">)</span></pre></p>

<h1><a class="toc-backref" id="hook-lifting" href="#hook-lifting">Hook lifting</a></h1><p>The hooks of a tuple type <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">B</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">)</span></span></tt> are generated by lifting the hooks of the involved types <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">B</span></span></tt>, ... to the tuple type. In other words, a copy <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">y</span></span></tt> is implemented as <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Operator">...</span></span></tt>, likewise for <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt>.</p>
<p>Other value-based compound types like <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">array</span></span></tt> are handled correspondingly. For <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> however, the compiler-generated hooks can be overridden. This can also be important to use an alternative traversal of the involved data structure that is more efficient or in order to avoid deep recursions.</p>

<h1><a class="toc-backref" id="hook-generation" href="#hook-generation">Hook generation</a></h1><p>The ability to override a hook leads to a phase ordering problem:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span>
  <span class="Comment"># error: destructor for 'f' called here before</span>
  <span class="Comment"># it was seen in this module.</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">discard</span></pre></p>
<p>The solution is to define <tt class="docutils literal"><span class="pre">proc `=destroy`[T](f: Foo[T])</span></tt> before it is used. The compiler generates implicit hooks for all types in <em>strategic places</em> so that an explicitly provided hook that comes too &quot;late&quot; can be detected reliably. These <em>strategic places</em> have been derived from the rewrite rules and are as follows:</p>
<ul class="simple"><li>In the construct <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span><span class="Operator">/</span><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Operator">...</span></span></tt> (var/let binding) hooks are generated for <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>.</li>
<li>In <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Operator">...</span></span></tt> (assignment) hooks are generated for <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>.</li>
<li>In <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span><span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">)</span></span></tt> (function call) hooks are generated for <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt>.</li>
<li>For every sink parameter <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">sink</span> <span class="Identifier">T</span></span></tt> the hooks are generated for <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>.</li>
</ul>

<h1><a class="toc-backref" id="nodestroy-pragma" href="#nodestroy-pragma">nodestroy pragma</a></h1><p>The experimental <span id="nodestroy_1">nodestroy</span> pragma inhibits hook injections. This can be used to specialize the object traversal in order to avoid deep recursions:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
  <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int32</span>
  <span class="Identifier">left</span><span class="Punctuation">,</span> <span class="Identifier">right</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>

<span class="Keyword">type</span> <span class="Identifier">Tree</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">Tree</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nodestroy</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># use an explicit stack so that we do not get stack overflows:</span>
  <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Node</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">root</span><span class="Punctuation">]</span>
  <span class="Keyword">while</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">&gt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
    <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">pop</span>
    <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">left</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">left</span><span class="Punctuation">)</span>
    <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">right</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">right</span><span class="Punctuation">)</span>
    <span class="Comment"># free the memory explicitly:</span>
    <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">dispose</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>
  <span class="Comment"># notice how even the destructor for 's' is not called implicitly</span>
  <span class="Comment"># anymore thanks to .nodestroy, so we have to call it on our own:</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span></pre></p>
<p>As can be seen from the example, this solution is hardly sufficient and should eventually be replaced by a better solution.</p>

<h1><a class="toc-backref" id="copy-on-write" href="#copy-on-write">Copy on write</a></h1><p>String literals are implemented as &quot;copy on write&quot;. When assigning a string literal to a variable, a copy of the literal won't be created. Instead the variable simply points to the literal. The literal is shared between different variables which are pointing to it. The copy operation is deferred until the first write.</p>
<p>For example:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>  <span class="Comment"># no copy</span>
<span class="Keyword">var</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">x</span>      <span class="Comment"># no copy</span>
<span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="CharLit">'h'</span>     <span class="Comment"># copy</span></pre></p>
<p>The abstraction fails for <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span> <span class="Identifier">x</span></span></tt> because whether the address is going to be used for mutations is unknown. <tt class="docutils literal"><span class="pre"><span class="Identifier">prepareMutation</span></span></tt> needs to be called before the &quot;address of&quot; operation. For example:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">x</span>

<span class="Identifier">prepareMutation</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span>
<span class="Identifier">moveMem</span><span class="Punctuation">(</span><span class="Keyword">addr</span> <span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Keyword">addr</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Identifier">y</span> <span class="Operator">==</span> <span class="StringLit">&quot;abc&quot;</span></pre></p>
</p>
    
  </div>
</div>

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