[www-releases] r336152 - Add 6.0.1 docs
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Mon Jul 2 16:21:47 PDT 2018
Added: www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl5.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl5.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl5.html (added)
+++ www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl5.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1379 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>5. Kaleidoscope: Extending the Language: Control Flow — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+ <link rel="next" title="6. Kaleidoscope: Extending the Language: User-defined Operators" href="OCamlLangImpl6.html" />
+ <link rel="prev" title="4. Kaleidoscope: Adding JIT and Optimizer Support" href="OCamlLangImpl4.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl4.html" title="4. Kaleidoscope: Adding JIT and Optimizer Support"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="kaleidoscope-extending-the-language-control-flow">
+<h1>5. Kaleidoscope: Extending the Language: Control Flow<a class="headerlink" href="#kaleidoscope-extending-the-language-control-flow" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#chapter-5-introduction" id="id1">Chapter 5 Introduction</a></li>
+<li><a class="reference internal" href="#if-then-else" id="id2">If/Then/Else</a><ul>
+<li><a class="reference internal" href="#lexer-extensions-for-if-then-else" id="id3">Lexer Extensions for If/Then/Else</a></li>
+<li><a class="reference internal" href="#ast-extensions-for-if-then-else" id="id4">AST Extensions for If/Then/Else</a></li>
+<li><a class="reference internal" href="#parser-extensions-for-if-then-else" id="id5">Parser Extensions for If/Then/Else</a></li>
+<li><a class="reference internal" href="#llvm-ir-for-if-then-else" id="id6">LLVM IR for If/Then/Else</a></li>
+<li><a class="reference internal" href="#code-generation-for-if-then-else" id="id7">Code Generation for If/Then/Else</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#for-loop-expression" id="id8">‘for’ Loop Expression</a><ul>
+<li><a class="reference internal" href="#lexer-extensions-for-the-for-loop" id="id9">Lexer Extensions for the ‘for’ Loop</a></li>
+<li><a class="reference internal" href="#ast-extensions-for-the-for-loop" id="id10">AST Extensions for the ‘for’ Loop</a></li>
+<li><a class="reference internal" href="#parser-extensions-for-the-for-loop" id="id11">Parser Extensions for the ‘for’ Loop</a></li>
+<li><a class="reference internal" href="#llvm-ir-for-the-for-loop" id="id12">LLVM IR for the ‘for’ Loop</a></li>
+<li><a class="reference internal" href="#code-generation-for-the-for-loop" id="id13">Code Generation for the ‘for’ Loop</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#full-code-listing" id="id14">Full Code Listing</a></li>
+</ul>
+</div>
+<div class="section" id="chapter-5-introduction">
+<h2><a class="toc-backref" href="#id1">5.1. Chapter 5 Introduction</a><a class="headerlink" href="#chapter-5-introduction" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to Chapter 5 of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. Parts 1-4 described the implementation of
+the simple Kaleidoscope language and included support for generating
+LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as
+presented, Kaleidoscope is mostly useless: it has no control flow other
+than call and return. This means that you can’t have conditional
+branches in the code, significantly limiting its power. In this episode
+of “build that compiler”, we’ll extend Kaleidoscope to have an
+if/then/else expression plus a simple ‘for’ loop.</p>
+</div>
+<div class="section" id="if-then-else">
+<h2><a class="toc-backref" href="#id2">5.2. If/Then/Else</a><a class="headerlink" href="#if-then-else" title="Permalink to this headline">¶</a></h2>
+<p>Extending Kaleidoscope to support if/then/else is quite straightforward.
+It basically requires adding lexer support for this “new” concept to the
+lexer, parser, AST, and LLVM code emitter. This example is nice, because
+it shows how easy it is to “grow” a language over time, incrementally
+extending it as new ideas are discovered.</p>
+<p>Before we get going on “how” we add this extension, lets talk about
+“what” we want. The basic idea is that we want to be able to write this
+sort of thing:</p>
+<div class="highlight-python"><pre>def fib(x)
+ if x < 3 then
+ 1
+ else
+ fib(x-1)+fib(x-2);</pre>
+</div>
+<p>In Kaleidoscope, every construct is an expression: there are no
+statements. As such, the if/then/else expression needs to return a value
+like any other. Since we’re using a mostly functional form, we’ll have
+it evaluate its conditional, then return the ‘then’ or ‘else’ value
+based on how the condition was resolved. This is very similar to the C
+”?:” expression.</p>
+<p>The semantics of the if/then/else expression is that it evaluates the
+condition to a boolean equality value: 0.0 is considered to be false and
+everything else is considered to be true. If the condition is true, the
+first subexpression is evaluated and returned, if the condition is
+false, the second subexpression is evaluated and returned. Since
+Kaleidoscope allows side-effects, this behavior is important to nail
+down.</p>
+<p>Now that we know what we “want”, lets break this down into its
+constituent pieces.</p>
+<div class="section" id="lexer-extensions-for-if-then-else">
+<h3><a class="toc-backref" href="#id3">5.2.1. Lexer Extensions for If/Then/Else</a><a class="headerlink" href="#lexer-extensions-for-if-then-else" title="Permalink to this headline">¶</a></h3>
+<p>The lexer extensions are straightforward. First we add new variants for
+the relevant tokens:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* control *)</span>
+<span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span> <span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nc">In</span>
+</pre></div>
+</div>
+<p>Once we have that, we recognize the new keywords in the lexer. This is
+pretty simple stuff:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="o">...</span>
+<span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+<span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+<span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="ast-extensions-for-if-then-else">
+<h3><a class="toc-backref" href="#id4">5.2.2. AST Extensions for If/Then/Else</a><a class="headerlink" href="#ast-extensions-for-if-then-else" title="Permalink to this headline">¶</a></h3>
+<p>To represent the new expression we add a new AST variant for it:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* variant for if/then/else. *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="k">of</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+<p>The AST variant just has pointers to the various subexpressions.</p>
+</div>
+<div class="section" id="parser-extensions-for-if-then-else">
+<h3><a class="toc-backref" href="#id5">5.2.3. Parser Extensions for If/Then/Else</a><a class="headerlink" href="#parser-extensions-for-if-then-else" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have the relevant tokens coming from the lexer and we have
+the AST node to build, our parsing logic is relatively straightforward.
+Next we add a new case for parsing a if-expression as a primary expression:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">...</span>
+ <span class="c">(* ifexpr ::= 'if' expr 'then' expr 'else' expr *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">c</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span> <span class="o">??</span> <span class="s2">"expected 'then'"</span><span class="o">;</span> <span class="n">t</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span> <span class="o">??</span> <span class="s2">"expected 'else'"</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">t</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="llvm-ir-for-if-then-else">
+<h3><a class="toc-backref" href="#id6">5.2.4. LLVM IR for If/Then/Else</a><a class="headerlink" href="#llvm-ir-for-if-then-else" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have it parsing and building the AST, the final piece is
+adding LLVM code generation support. This is the most interesting part
+of the if/then/else example, because this is where it starts to
+introduce new concepts. All of the code above has been thoroughly
+described in previous chapters.</p>
+<p>To motivate the code we want to produce, lets take a look at a simple
+example. Consider:</p>
+<div class="highlight-python"><pre>extern foo();
+extern bar();
+def baz(x) if x then foo() else bar();</pre>
+</div>
+<p>If you disable optimizations, the code you’ll (soon) get from
+Kaleidoscope looks like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="kt">double</span> <span class="vg">@foo</span><span class="p">()</span>
+
+<span class="k">declare</span> <span class="kt">double</span> <span class="vg">@bar</span><span class="p">()</span>
+
+<span class="k">define</span> <span class="kt">double</span> <span class="vg">@baz</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span>
+
+<span class="nl">then:</span> <span class="c">; preds = %entry</span>
+ <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span> <span class="c">; preds = %entry</span>
+ <span class="nv">%calltmp1</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@bar</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">ifcont:</span> <span class="c">; preds = %else, %then</span>
+ <span class="nv">%iftmp</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%then</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%calltmp1</span><span class="p">,</span> <span class="nv">%else</span> <span class="p">]</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%iftmp</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To visualize the control flow graph, you can use a nifty feature of the
+LLVM ‘<a class="reference external" href="http://llvm.org/cmds/opt.html">opt</a>‘ tool. If you put this LLVM
+IR into “t.ll” and run “<tt class="docutils literal"><span class="pre">llvm-as</span> <span class="pre"><</span> <span class="pre">t.ll</span> <span class="pre">|</span> <span class="pre">opt</span> <span class="pre">-analyze</span> <span class="pre">-view-cfg</span></tt>”, <a class="reference external" href="../ProgrammersManual.html#viewing-graphs-while-debugging-code">a
+window will pop up</a> and you’ll
+see this graph:</p>
+<div class="figure align-center">
+<img alt="Example CFG" src="../_images/LangImpl05-cfg.png" />
+<p class="caption">Example CFG</p>
+</div>
+<p>Another way to get this is to call
+“<tt class="docutils literal"><span class="pre">Llvm_analysis.view_function_cfg</span> <span class="pre">f</span></tt>” or
+“<tt class="docutils literal"><span class="pre">Llvm_analysis.view_function_cfg_only</span> <span class="pre">f</span></tt>” (where <tt class="docutils literal"><span class="pre">f</span></tt> is a
+“<tt class="docutils literal"><span class="pre">Function</span></tt>”) either by inserting actual calls into the code and
+recompiling or by calling these in the debugger. LLVM has many nice
+features for visualizing various graphs.</p>
+<p>Getting back to the generated code, it is fairly simple: the entry block
+evaluates the conditional expression (“x” in our case here) and compares
+the result to 0.0 with the “<tt class="docutils literal"><span class="pre">fcmp</span> <span class="pre">one</span></tt>” instruction (‘one’ is “Ordered
+and Not Equal”). Based on the result of this expression, the code jumps
+to either the “then” or “else” blocks, which contain the expressions for
+the true/false cases.</p>
+<p>Once the then/else blocks are finished executing, they both branch back
+to the ‘ifcont’ block to execute the code that happens after the
+if/then/else. In this case the only thing left to do is to return to the
+caller of the function. The question then becomes: how does the code
+know which expression to return?</p>
+<p>The answer to this question involves an important SSA operation: the
+<a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">Phi
+operation</a>.
+If you’re not familiar with SSA, <a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">the wikipedia
+article</a>
+is a good introduction and there are various other introductions to it
+available on your favorite search engine. The short version is that
+“execution” of the Phi operation requires “remembering” which block
+control came from. The Phi operation takes on the value corresponding to
+the input control block. In this case, if control comes in from the
+“then” block, it gets the value of “calltmp”. If control comes from the
+“else” block, it gets the value of “calltmp1”.</p>
+<p>At this point, you are probably starting to think “Oh no! This means my
+simple and elegant front-end will have to start generating SSA form in
+order to use LLVM!”. Fortunately, this is not the case, and we strongly
+advise <em>not</em> implementing an SSA construction algorithm in your
+front-end unless there is an amazingly good reason to do so. In
+practice, there are two sorts of values that float around in code
+written for your average imperative programming language that might need
+Phi nodes:</p>
+<ol class="arabic simple">
+<li>Code that involves user variables: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">1;</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">x</span> <span class="pre">+</span> <span class="pre">1;</span></tt></li>
+<li>Values that are implicit in the structure of your AST, such as the
+Phi node in this case.</li>
+</ol>
+<p>In <a class="reference external" href="OCamlLangImpl7.html">Chapter 7</a> of this tutorial (“mutable
+variables”), we’ll talk about #1 in depth. For now, just believe me that
+you don’t need SSA construction to handle this case. For #2, you have
+the choice of using the techniques that we will describe for #1, or you
+can insert Phi nodes directly, if convenient. In this case, it is really
+really easy to generate the Phi node, so we choose to do it directly.</p>
+<p>Okay, enough of the motivation and overview, lets generate code!</p>
+</div>
+<div class="section" id="code-generation-for-if-then-else">
+<h3><a class="toc-backref" href="#id7">5.2.5. Code Generation for If/Then/Else</a><a class="headerlink" href="#code-generation-for-if-then-else" title="Permalink to this headline">¶</a></h3>
+<p>In order to generate code for this, we implement the <tt class="docutils literal"><span class="pre">Codegen</span></tt> method
+for <tt class="docutils literal"><span class="pre">IfExprAST</span></tt>:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">cond</span><span class="o">,</span> <span class="n">then_</span><span class="o">,</span> <span class="n">else_</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">cond</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0 *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">cond_val</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">cond</span> <span class="n">zero</span> <span class="s2">"ifcond"</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>This code is straightforward and similar to what we saw before. We emit
+the expression for the condition, then compare that value to zero to get
+a truth value as a 1-bit (bool) value.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Grab the first block so that we might later add the conditional branch</span>
+<span class="c"> * to it at the end of the function. *)</span>
+<span class="k">let</span> <span class="n">start_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">start_bb</span> <span class="k">in</span>
+
+<span class="k">let</span> <span class="n">then_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"then"</span> <span class="n">the_function</span> <span class="k">in</span>
+<span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>As opposed to the <a class="reference external" href="LangImpl05.html">C++ tutorial</a>, we have to build our
+basic blocks bottom up since we can’t have dangling BasicBlocks. We
+start off by saving a pointer to the first block (which might not be the
+entry block), which we’ll need to build a conditional branch later. We
+do this by asking the <tt class="docutils literal"><span class="pre">builder</span></tt> for the current BasicBlock. The fourth
+line gets the current Function object that is being built. It gets this
+by the <tt class="docutils literal"><span class="pre">start_bb</span></tt> for its “parent” (the function it is currently
+embedded into).</p>
+<p>Once it has that, it creates one block. It is automatically appended
+into the function’s list of blocks.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Emit 'then' value. *)</span>
+<span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+<span class="k">let</span> <span class="n">then_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">then_</span> <span class="k">in</span>
+
+<span class="c">(* Codegen of 'then' can change the current block, update then_bb for the</span>
+<span class="c"> * phi. We create a new name because one is used for the phi node, and the</span>
+<span class="c"> * other is used for the conditional branch. *)</span>
+<span class="k">let</span> <span class="n">new_then_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>We move the builder to start inserting into the “then” block. Strictly
+speaking, this call moves the insertion point to be at the end of the
+specified block. However, since the “then” block is empty, it also
+starts out by inserting at the beginning of the block. :)</p>
+<p>Once the insertion point is set, we recursively codegen the “then”
+expression from the AST.</p>
+<p>The final line here is quite subtle, but is very important. The basic
+issue is that when we create the Phi node in the merge block, we need to
+set up the block/value pairs that indicate how the Phi will work.
+Importantly, the Phi node expects to have an entry for each predecessor
+of the block in the CFG. Why then, are we getting the current block when
+we just set it to ThenBB 5 lines above? The problem is that the “Then”
+expression may actually itself change the block that the Builder is
+emitting into if, for example, it contains a nested “if/then/else”
+expression. Because calling Codegen recursively could arbitrarily change
+the notion of the current block, we are required to get an up-to-date
+value for code that will set up the Phi node.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Emit 'else' value. *)</span>
+<span class="k">let</span> <span class="n">else_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"else"</span> <span class="n">the_function</span> <span class="k">in</span>
+<span class="n">position_at_end</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">;</span>
+<span class="k">let</span> <span class="n">else_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">else_</span> <span class="k">in</span>
+
+<span class="c">(* Codegen of 'else' can change the current block, update else_bb for the</span>
+<span class="c"> * phi. *)</span>
+<span class="k">let</span> <span class="n">new_else_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Code generation for the ‘else’ block is basically identical to codegen
+for the ‘then’ block.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Emit merge block. *)</span>
+<span class="k">let</span> <span class="n">merge_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"ifcont"</span> <span class="n">the_function</span> <span class="k">in</span>
+<span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+<span class="k">let</span> <span class="n">incoming</span> <span class="o">=</span> <span class="o">[(</span><span class="n">then_val</span><span class="o">,</span> <span class="n">new_then_bb</span><span class="o">);</span> <span class="o">(</span><span class="n">else_val</span><span class="o">,</span> <span class="n">new_else_bb</span><span class="o">)]</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">phi</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="n">incoming</span> <span class="s2">"iftmp"</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>The first two lines here are now familiar: the first adds the “merge”
+block to the Function object. The second changes the insertion
+point so that newly created code will go into the “merge” block. Once
+that is done, we need to create the PHI node and set up the block/value
+pairs for the PHI.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Return to the start block to add the conditional branch. *)</span>
+<span class="n">position_at_end</span> <span class="n">start_bb</span> <span class="n">builder</span><span class="o">;</span>
+<span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">cond_val</span> <span class="n">then_bb</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">);</span>
+</pre></div>
+</div>
+<p>Once the blocks are created, we can emit the conditional branch that
+chooses between them. Note that creating new blocks does not implicitly
+affect the IRBuilder, so it is still inserting into the block that the
+condition went into. This is why we needed to save the “start” block.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Set a unconditional branch at the end of the 'then' block and the</span>
+<span class="c"> * 'else' block to the 'merge' block. *)</span>
+<span class="n">position_at_end</span> <span class="n">new_then_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+<span class="n">position_at_end</span> <span class="n">new_else_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+<span class="c">(* Finally, set the builder to the end of the merge block. *)</span>
+<span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+<span class="n">phi</span>
+</pre></div>
+</div>
+<p>To finish off the blocks, we create an unconditional branch to the merge
+block. One interesting (and very important) aspect of the LLVM IR is
+that it <a class="reference external" href="../LangRef.html#functionstructure">requires all basic blocks to be
+“terminated”</a> with a <a class="reference external" href="../LangRef.html#terminators">control flow
+instruction</a> such as return or branch.
+This means that all control flow, <em>including fall throughs</em> must be made
+explicit in the LLVM IR. If you violate this rule, the verifier will
+emit an error.</p>
+<p>Finally, the CodeGen function returns the phi node as the value computed
+by the if/then/else expression. In our example above, this returned
+value will feed into the code for the top-level function, which will
+create the return instruction.</p>
+<p>Overall, we now have the ability to execute conditional code in
+Kaleidoscope. With this extension, Kaleidoscope is a fairly complete
+language that can calculate a wide variety of numeric functions. Next up
+we’ll add another useful expression that is familiar from non-functional
+languages...</p>
+</div>
+</div>
+<div class="section" id="for-loop-expression">
+<h2><a class="toc-backref" href="#id8">5.3. ‘for’ Loop Expression</a><a class="headerlink" href="#for-loop-expression" title="Permalink to this headline">¶</a></h2>
+<p>Now that we know how to add basic control flow constructs to the
+language, we have the tools to add more powerful things. Lets add
+something more aggressive, a ‘for’ expression:</p>
+<div class="highlight-python"><pre>extern putchard(char);
+def printstar(n)
+ for i = 1, i < n, 1.0 in
+ putchard(42); # ascii 42 = '*'
+
+# print 100 '*' characters
+printstar(100);</pre>
+</div>
+<p>This expression defines a new variable (“i” in this case) which iterates
+from a starting value, while the condition (“i < n” in this case) is
+true, incrementing by an optional step value (“1.0” in this case). If
+the step value is omitted, it defaults to 1.0. While the loop is true,
+it executes its body expression. Because we don’t have anything better
+to return, we’ll just define the loop as always returning 0.0. In the
+future when we have mutable variables, it will get more useful.</p>
+<p>As before, lets talk about the changes that we need to Kaleidoscope to
+support this.</p>
+<div class="section" id="lexer-extensions-for-the-for-loop">
+<h3><a class="toc-backref" href="#id9">5.3.1. Lexer Extensions for the ‘for’ Loop</a><a class="headerlink" href="#lexer-extensions-for-the-for-loop" title="Permalink to this headline">¶</a></h3>
+<p>The lexer extensions are the same sort of thing as for if/then/else:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="o">...</span> <span class="k">in</span> <span class="nn">Token</span><span class="p">.</span><span class="n">token</span> <span class="o">...</span>
+<span class="c">(* control *)</span>
+<span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span>
+<span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nn">In</span>
+
+<span class="p">...</span> <span class="n">in</span> <span class="nn">Lexer</span><span class="p">.</span><span class="n">lex_ident</span><span class="o">...</span>
+ <span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="ast-extensions-for-the-for-loop">
+<h3><a class="toc-backref" href="#id10">5.3.2. AST Extensions for the ‘for’ Loop</a><a class="headerlink" href="#ast-extensions-for-the-for-loop" title="Permalink to this headline">¶</a></h3>
+<p>The AST variant is just as simple. It basically boils down to capturing
+the variable name and the constituent expressions in the node.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* variant for for/in. *)</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="parser-extensions-for-the-for-loop">
+<h3><a class="toc-backref" href="#id11">5.3.3. Parser Extensions for the ‘for’ Loop</a><a class="headerlink" href="#parser-extensions-for-the-for-loop" title="Permalink to this headline">¶</a></h3>
+<p>The parser code is also fairly standard. The only interesting thing here
+is handling of the optional step value. The parser code handles it by
+checking to see if the second comma is present. If not, it sets the step
+value to null in the AST node:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">...</span>
+ <span class="c">(* forexpr</span>
+<span class="c"> ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after for"</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span> <span class="o">??</span> <span class="s2">"expected '=' after for"</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span>
+ <span class="n">start</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span> <span class="o">??</span> <span class="s2">"expected ',' after for"</span><span class="o">;</span>
+ <span class="n">end_</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">step</span> <span class="o">=</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">step</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">step</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="k">in</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected 'in' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected '=' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="llvm-ir-for-the-for-loop">
+<h3><a class="toc-backref" href="#id12">5.3.4. LLVM IR for the ‘for’ Loop</a><a class="headerlink" href="#llvm-ir-for-the-for-loop" title="Permalink to this headline">¶</a></h3>
+<p>Now we get to the good part: the LLVM IR we want to generate for this
+thing. With the simple example above, we get this LLVM IR (note that
+this dump is generated with optimizations disabled for clarity):</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="kt">double</span> <span class="vg">@putchard</span><span class="p">(</span><span class="kt">double</span><span class="p">)</span>
+
+<span class="k">define</span> <span class="kt">double</span> <span class="vg">@printstar</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%n</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="c">; initial value = 1.0 (inlined into phi)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%loop</span>
+
+<span class="nl">loop:</span> <span class="c">; preds = %loop, %entry</span>
+ <span class="nv">%i</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="m">1.000000e+00</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%nextvar</span><span class="p">,</span> <span class="nv">%loop</span> <span class="p">]</span>
+ <span class="c">; body</span>
+ <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@putchard</span><span class="p">(</span><span class="kt">double</span> <span class="m">4.200000e+01</span><span class="p">)</span>
+ <span class="c">; increment</span>
+ <span class="nv">%nextvar</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%i</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+
+ <span class="c">; termination test</span>
+ <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%i</span><span class="p">,</span> <span class="nv">%n</span>
+ <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+ <span class="nv">%loopcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%loopcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%afterloop</span>
+
+<span class="nl">afterloop:</span> <span class="c">; preds = %loop</span>
+ <span class="c">; loop always returns 0.0</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="m">0.000000e+00</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This loop contains all the same constructs we saw before: a phi node,
+several expressions, and some basic blocks. Lets see how this fits
+together.</p>
+</div>
+<div class="section" id="code-generation-for-the-for-loop">
+<h3><a class="toc-backref" href="#id13">5.3.5. Code Generation for the ‘for’ Loop</a><a class="headerlink" href="#code-generation-for-the-for-loop" title="Permalink to this headline">¶</a></h3>
+<p>The first part of Codegen is very simple: we just output the start
+expression for the loop value:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+ <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>With this out of the way, the next step is to set up the LLVM basic
+block for the start of the loop body. In the case above, the whole loop
+body is one block, but remember that the body code itself could consist
+of multiple blocks (e.g. if it contains an if/then/else or a for/in
+expression).</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Make the new basic block for the loop header, inserting after current</span>
+<span class="c"> * block. *)</span>
+<span class="k">let</span> <span class="n">preheader_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">preheader_bb</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">loop_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"loop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+<span class="c">(* Insert an explicit fall through from the current block to the</span>
+<span class="c"> * loop_bb. *)</span>
+<span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">);</span>
+</pre></div>
+</div>
+<p>This code is similar to what we saw for if/then/else. Because we will
+need it to create the Phi node, we remember the block that falls through
+into the loop. Once we have that, we create the actual block that starts
+the loop and create an unconditional branch for the fall-through between
+the two blocks.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Start insertion in loop_bb. *)</span>
+<span class="n">position_at_end</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+<span class="c">(* Start the PHI node with an entry for start. *)</span>
+<span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="o">[(</span><span class="n">start_val</span><span class="o">,</span> <span class="n">preheader_bb</span><span class="o">)]</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Now that the “preheader” for the loop is set up, we switch to emitting
+code for the loop body. To begin with, we move the insertion point and
+create the PHI node for the loop induction variable. Since we already
+know the incoming value for the starting value, we add it to the Phi
+node. Note that the Phi will eventually get a second value for the
+backedge, but we can’t set it up yet (because it doesn’t exist!).</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c"> * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c"> * now. *)</span>
+<span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+ <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+<span class="k">in</span>
+<span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">variable</span><span class="o">;</span>
+
+<span class="c">(* Emit the body of the loop. This, like any other expr, can change the</span>
+<span class="c"> * current BB. Note that we ignore the value computed by the body, but</span>
+<span class="c"> * don't allow an error *)</span>
+<span class="n">ignore</span> <span class="o">(</span><span class="n">codegen_expr</span> <span class="n">body</span><span class="o">);</span>
+</pre></div>
+</div>
+<p>Now the code starts to get more interesting. Our ‘for’ loop introduces a
+new variable to the symbol table. This means that our symbol table can
+now contain either function arguments or loop variables. To handle this,
+before we codegen the body of the loop, we add the loop variable as the
+current value for its name. Note that it is possible that there is a
+variable of the same name in the outer scope. It would be easy to make
+this an error (emit an error and return null if there is already an
+entry for VarName) but we choose to allow shadowing of variables. In
+order to handle this correctly, we remember the Value that we are
+potentially shadowing in <tt class="docutils literal"><span class="pre">old_val</span></tt> (which will be None if there is no
+shadowed variable).</p>
+<p>Once the loop variable is set into the symbol table, the code
+recursively codegen’s the body. This allows the body to use the loop
+variable: any references to it will naturally find it in the symbol
+table.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Emit the step value. *)</span>
+<span class="k">let</span> <span class="n">step_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">step</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">step</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">step</span>
+ <span class="c">(* If not specified, use 1.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">1</span><span class="o">.</span><span class="mi">0</span>
+<span class="k">in</span>
+
+<span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">variable</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Now that the body is emitted, we compute the next value of the iteration
+variable by adding the step value, or 1.0 if it isn’t present.
+‘<tt class="docutils literal"><span class="pre">next_var</span></tt>‘ will be the value of the loop variable on the next
+iteration of the loop.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Compute the end condition. *)</span>
+<span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+<span class="c">(* Convert condition to a bool by comparing equal to 0.0. *)</span>
+<span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">end_cond</span> <span class="n">zero</span> <span class="s2">"loopcond"</span> <span class="n">builder</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Finally, we evaluate the exit value of the loop, to determine whether
+the loop should exit. This mirrors the condition evaluation for the
+if/then/else statement.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Create the "after loop" block and insert it. *)</span>
+<span class="k">let</span> <span class="n">loop_end_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+<span class="k">let</span> <span class="n">after_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"afterloop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+<span class="c">(* Insert the conditional branch into the end of loop_end_bb. *)</span>
+<span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">end_cond</span> <span class="n">loop_bb</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+<span class="c">(* Any new code will be inserted in after_bb. *)</span>
+<span class="n">position_at_end</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>With the code for the body of the loop complete, we just need to finish
+up the control flow for it. This code remembers the end block (for the
+phi node), then creates the block for the loop exit (“afterloop”). Based
+on the value of the exit condition, it creates a conditional branch that
+chooses between executing the loop again and exiting the loop. Any
+future code is emitted in the “afterloop” block, so it sets the
+insertion position to it.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Add a new entry to the PHI node for the backedge. *)</span>
+<span class="n">add_incoming</span> <span class="o">(</span><span class="n">next_var</span><span class="o">,</span> <span class="n">loop_end_bb</span><span class="o">)</span> <span class="n">variable</span><span class="o">;</span>
+
+<span class="c">(* Restore the unshadowed variable. *)</span>
+<span class="k">begin</span> <span class="k">match</span> <span class="n">old_val</span> <span class="k">with</span>
+<span class="o">|</span> <span class="nc">Some</span> <span class="n">old_val</span> <span class="o">-></span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_val</span>
+<span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+<span class="k">end</span><span class="o">;</span>
+
+<span class="c">(* for expr always returns 0.0. *)</span>
+<span class="n">const_null</span> <span class="n">double_type</span>
+</pre></div>
+</div>
+<p>The final code handles various cleanups: now that we have the
+“<tt class="docutils literal"><span class="pre">next_var</span></tt>” value, we can add the incoming value to the loop PHI
+node. After that, we remove the loop variable from the symbol table, so
+that it isn’t in scope after the for loop. Finally, code generation of
+the for loop always returns 0.0, so that is what we return from
+<tt class="docutils literal"><span class="pre">Codegen.codegen_expr</span></tt>.</p>
+<p>With this, we conclude the “adding control flow to Kaleidoscope” chapter
+of the tutorial. In this chapter we added two control flow constructs,
+and used them to motivate a couple of aspects of the LLVM IR that are
+important for front-end implementors to know. In the next chapter of our
+saga, we will get a bit crazier and add <a class="reference external" href="OCamlLangImpl6.html">user-defined
+operators</a> to our poor innocent language.</p>
+</div>
+</div>
+<div class="section" id="full-code-listing">
+<h2><a class="toc-backref" href="#id14">5.4. Full Code Listing</a><a class="headerlink" href="#full-code-listing" title="Permalink to this headline">¶</a></h2>
+<p>Here is the complete code listing for our running example, enhanced with
+the if/then/else and for expressions.. To build this example, use:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Compile</span>
+ocamlbuild toy.byte
+<span class="c"># Run</span>
+./toy.byte
+</pre></div>
+</div>
+<p>Here is the code:</p>
+<dl class="docutils">
+<dt>_tags:</dt>
+<dd><div class="first last highlight-python"><pre><{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
+<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
+<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
+<*.{byte,native}>: use_llvm_scalar_opts, use_bindings</pre>
+</div>
+</dd>
+<dt>myocamlbuild.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="k">open</span> <span class="nc">Ocamlbuild_plugin</span><span class="o">;;</span>
+
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_analysis"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_executionengine"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_target"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_scalar_opts"</span><span class="o">;;</span>
+
+<span class="n">flag</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"g++"</span><span class="o">]</span> <span class="o">(</span><span class="nc">S</span><span class="o">[</span><span class="nc">A</span><span class="s2">"-cc"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"g++"</span><span class="o">]);;</span>
+<span class="n">dep</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"use_bindings"</span><span class="o">]</span> <span class="o">[</span><span class="s2">"bindings.o"</span><span class="o">];;</span>
+</pre></div>
+</div>
+</dd>
+<dt>token.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer Tokens</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of</span>
+<span class="c"> * these others for known things. *)</span>
+<span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+ <span class="c">(* commands *)</span>
+ <span class="o">|</span> <span class="nc">Def</span> <span class="o">|</span> <span class="nc">Extern</span>
+
+ <span class="c">(* primary *)</span>
+ <span class="o">|</span> <span class="nc">Ident</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* unknown *)</span>
+ <span class="o">|</span> <span class="nc">Kwd</span> <span class="k">of</span> <span class="kt">char</span>
+
+ <span class="c">(* control *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nc">In</span>
+</pre></div>
+</div>
+</dd>
+<dt>lexer.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">lex</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Skip any whitespace. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">' '</span> <span class="o">|</span> <span class="sc">'\n'</span> <span class="o">|</span> <span class="sc">'\r'</span> <span class="o">|</span> <span class="sc">'\t'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">lex</span> <span class="n">stream</span>
+
+ <span class="c">(* identifier: [a-zA-Z][a-zA-Z0-9] *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* number: [0-9.]+ *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* Comment until end of line. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'#'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="n">lex_comment</span> <span class="n">stream</span>
+
+ <span class="c">(* Otherwise, just return the character as its ascii value. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">;</span> <span class="n">lex</span> <span class="n">stream</span> <span class="o">>]</span>
+
+ <span class="c">(* end of stream. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_number</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="o">|</span> <span class="sc">'.'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="o">(</span><span class="n">float_of_string</span> <span class="o">(</span><span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span><span class="o">));</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="o">|</span> <span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_comment</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'\n'</span><span class="o">);</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">lex_comment</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</dd>
+<dt>ast.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Abstract Syntax Tree (aka Parse Tree)</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* expr - Base type for all expression nodes. *)</span>
+<span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="c">(* variant for numeric literals like "1.0". *)</span>
+ <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* variant for referencing a variable, like "a". *)</span>
+ <span class="o">|</span> <span class="nc">Variable</span> <span class="k">of</span> <span class="kt">string</span>
+
+ <span class="c">(* variant for a binary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for function calls. *)</span>
+ <span class="o">|</span> <span class="nc">Call</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="kt">array</span>
+
+ <span class="c">(* variant for if/then/else. *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="k">of</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for for/in. *)</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span> <span class="o">*</span> <span class="n">expr</span>
+
+<span class="c">(* proto - This type represents the "prototype" for a function, which captures</span>
+<span class="c"> * its name, and its argument names (thus implicitly the number of arguments the</span>
+<span class="c"> * function takes). *)</span>
+<span class="k">type</span> <span class="n">proto</span> <span class="o">=</span> <span class="nc">Prototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span>
+
+<span class="c">(* func - This type represents a function definition itself. *)</span>
+<span class="k">type</span> <span class="n">func</span> <span class="o">=</span> <span class="nc">Function</span> <span class="k">of</span> <span class="n">proto</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+</dd>
+<dt>parser.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===---------------------------------------------------------------------===</span>
+<span class="c"> * Parser</span>
+<span class="c"> *===---------------------------------------------------------------------===*)</span>
+
+<span class="c">(* binop_precedence - This holds the precedence for each binary operator that is</span>
+<span class="c"> * defined *)</span>
+<span class="k">let</span> <span class="n">binop_precedence</span><span class="o">:(</span><span class="kt">char</span><span class="o">,</span> <span class="kt">int</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+
+<span class="c">(* precedence - Get the precedence of the pending binary operator token. *)</span>
+<span class="k">let</span> <span class="n">precedence</span> <span class="n">c</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="o">-</span><span class="mi">1</span>
+
+<span class="c">(* primary</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= numberexpr</span>
+<span class="c"> * ::= parenexpr</span>
+<span class="c"> * ::= ifexpr</span>
+<span class="c"> * ::= forexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* numberexpr ::= number *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span>
+
+ <span class="c">(* parenexpr ::= '(' expression ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+
+ <span class="c">(* identifierexpr</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= identifier '(' argumentexpr ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_ident</span> <span class="n">id</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Call. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span><span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+
+ <span class="c">(* Simple variable ref. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">id</span>
+ <span class="k">in</span>
+ <span class="n">parse_ident</span> <span class="n">id</span> <span class="n">stream</span>
+
+ <span class="c">(* ifexpr ::= 'if' expr 'then' expr 'else' expr *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">c</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span> <span class="o">??</span> <span class="s2">"expected 'then'"</span><span class="o">;</span> <span class="n">t</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span> <span class="o">??</span> <span class="s2">"expected 'else'"</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">t</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+ <span class="c">(* forexpr</span>
+<span class="c"> ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after for"</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span> <span class="o">??</span> <span class="s2">"expected '=' after for"</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span>
+ <span class="n">start</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span> <span class="o">??</span> <span class="s2">"expected ',' after for"</span><span class="o">;</span>
+ <span class="n">end_</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">step</span> <span class="o">=</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">step</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">step</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="k">in</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected 'in' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected '=' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"unknown token when expecting an expression."</span><span class="o">)</span>
+
+<span class="c">(* binoprhs</span>
+<span class="c"> * ::= ('+' primary)* *)</span>
+<span class="ow">and</span> <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="c">(* If this is a binop, find its precedence. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">)</span> <span class="k">when</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">mem</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">token_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c</span> <span class="k">in</span>
+
+ <span class="c">(* If this is a binop that binds at least as tightly as the current binop,</span>
+<span class="c"> * consume it, otherwise we are done. *)</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">expr_prec</span> <span class="k">then</span> <span class="n">lhs</span> <span class="k">else</span> <span class="k">begin</span>
+ <span class="c">(* Eat the binop. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Parse the primary expression after the binary operator. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span> <span class="n">parse_primary</span> <span class="n">stream</span> <span class="k">in</span>
+
+ <span class="c">(* Okay, we know this is a binop. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c2</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* If BinOp binds less tightly with rhs than the operator after</span>
+<span class="c"> * rhs, let the pending operator take rhs as its lhs. *)</span>
+ <span class="k">let</span> <span class="n">next_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c2</span> <span class="k">in</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">next_prec</span>
+ <span class="k">then</span> <span class="n">parse_bin_rhs</span> <span class="o">(</span><span class="n">token_prec</span> <span class="o">+</span> <span class="mi">1</span><span class="o">)</span> <span class="n">rhs</span> <span class="n">stream</span>
+ <span class="k">else</span> <span class="n">rhs</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">rhs</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Merge lhs/rhs. *)</span>
+ <span class="k">let</span> <span class="n">lhs</span> <span class="o">=</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">lhs</span>
+
+<span class="c">(* expression</span>
+<span class="c"> * ::= primary binoprhs *)</span>
+<span class="ow">and</span> <span class="n">parse_expr</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">lhs</span><span class="o">=</span><span class="n">parse_primary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_bin_rhs</span> <span class="mi">0</span> <span class="n">lhs</span> <span class="n">stream</span>
+
+<span class="c">(* prototype</span>
+<span class="c"> * ::= id '(' id* ')' *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+
+ <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* success. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+
+<span class="c">(* definition ::= 'def' prototype expression *)</span>
+<span class="k">let</span> <span class="n">parse_definition</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">p</span><span class="o">=</span><span class="n">parse_prototype</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">p</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* toplevelexpr ::= expression *)</span>
+<span class="k">let</span> <span class="n">parse_toplevel</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* Make an anonymous proto. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="s2">""</span><span class="o">,</span> <span class="o">[||]),</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* external ::= 'extern' prototype *)</span>
+<span class="k">let</span> <span class="n">parse_extern</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_prototype</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>codegen.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Code Generation</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+
+<span class="k">exception</span> <span class="nc">Error</span> <span class="k">of</span> <span class="kt">string</span>
+
+<span class="k">let</span> <span class="n">context</span> <span class="o">=</span> <span class="n">global_context</span> <span class="bp">()</span>
+<span class="k">let</span> <span class="n">the_module</span> <span class="o">=</span> <span class="n">create_module</span> <span class="n">context</span> <span class="s2">"my cool jit"</span>
+<span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span> <span class="n">context</span>
+<span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+<span class="k">let</span> <span class="n">double_type</span> <span class="o">=</span> <span class="n">double_type</span> <span class="n">context</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+ <span class="o">(</span><span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">))</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">lhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">lhs</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">rhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+ <span class="k">begin</span>
+ <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'+'</span> <span class="o">-></span> <span class="n">build_add</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"addtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'-'</span> <span class="o">-></span> <span class="n">build_sub</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"subtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'*'</span> <span class="o">-></span> <span class="n">build_mul</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"multmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'<'</span> <span class="o">-></span>
+ <span class="c">(* Convert bool 0/1 to double 0.0 or 1.0 *)</span>
+ <span class="k">let</span> <span class="n">i</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">Ult</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"cmptmp"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">build_uitofp</span> <span class="n">i</span> <span class="n">double_type</span> <span class="s2">"booltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"invalid binary operator"</span><span class="o">)</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">callee</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Look up the name in the module table. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown function referenced"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="n">callee</span> <span class="k">in</span>
+
+ <span class="c">(* If argument mismatch error. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">params</span> <span class="o">==</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="k">then</span> <span class="bp">()</span> <span class="k">else</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"incorrect # arguments passed"</span><span class="o">);</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">map</span> <span class="n">codegen_expr</span> <span class="n">args</span> <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="n">args</span> <span class="s2">"calltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">cond</span><span class="o">,</span> <span class="n">then_</span><span class="o">,</span> <span class="n">else_</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">cond</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0 *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">cond_val</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">cond</span> <span class="n">zero</span> <span class="s2">"ifcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Grab the first block so that we might later add the conditional branch</span>
+<span class="c"> * to it at the end of the function. *)</span>
+ <span class="k">let</span> <span class="n">start_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">start_bb</span> <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">then_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"then"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'then' value. *)</span>
+ <span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">then_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">then_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'then' can change the current block, update then_bb for the</span>
+<span class="c"> * phi. We create a new name because one is used for the phi node, and the</span>
+<span class="c"> * other is used for the conditional branch. *)</span>
+ <span class="k">let</span> <span class="n">new_then_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'else' value. *)</span>
+ <span class="k">let</span> <span class="n">else_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"else"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">else_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">else_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'else' can change the current block, update else_bb for the</span>
+<span class="c"> * phi. *)</span>
+ <span class="k">let</span> <span class="n">new_else_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit merge block. *)</span>
+ <span class="k">let</span> <span class="n">merge_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"ifcont"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">incoming</span> <span class="o">=</span> <span class="o">[(</span><span class="n">then_val</span><span class="o">,</span> <span class="n">new_then_bb</span><span class="o">);</span> <span class="o">(</span><span class="n">else_val</span><span class="o">,</span> <span class="n">new_else_bb</span><span class="o">)]</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">phi</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="n">incoming</span> <span class="s2">"iftmp"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Return to the start block to add the conditional branch. *)</span>
+ <span class="n">position_at_end</span> <span class="n">start_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">cond_val</span> <span class="n">then_bb</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Set a unconditional branch at the end of the 'then' block and the</span>
+<span class="c"> * 'else' block to the 'merge' block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">new_then_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="n">position_at_end</span> <span class="n">new_else_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Finally, set the builder to the end of the merge block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="n">phi</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+ <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+ <span class="c">(* Make the new basic block for the loop header, inserting after current</span>
+<span class="c"> * block. *)</span>
+ <span class="k">let</span> <span class="n">preheader_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">preheader_bb</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">loop_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"loop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert an explicit fall through from the current block to the</span>
+<span class="c"> * loop_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Start insertion in loop_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Start the PHI node with an entry for start. *)</span>
+ <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="o">[(</span><span class="n">start_val</span><span class="o">,</span> <span class="n">preheader_bb</span><span class="o">)]</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c"> * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c"> * now. *)</span>
+ <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+ <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">variable</span><span class="o">;</span>
+
+ <span class="c">(* Emit the body of the loop. This, like any other expr, can change the</span>
+<span class="c"> * current BB. Note that we ignore the value computed by the body, but</span>
+<span class="c"> * don't allow an error *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">codegen_expr</span> <span class="n">body</span><span class="o">);</span>
+
+ <span class="c">(* Emit the step value. *)</span>
+ <span class="k">let</span> <span class="n">step_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">step</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">step</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">step</span>
+ <span class="c">(* If not specified, use 1.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">1</span><span class="o">.</span><span class="mi">0</span>
+ <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">variable</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Compute the end condition. *)</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0. *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">end_cond</span> <span class="n">zero</span> <span class="s2">"loopcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Create the "after loop" block and insert it. *)</span>
+ <span class="k">let</span> <span class="n">loop_end_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">after_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"afterloop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert the conditional branch into the end of loop_end_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">end_cond</span> <span class="n">loop_bb</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Any new code will be inserted in after_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Add a new entry to the PHI node for the backedge. *)</span>
+ <span class="n">add_incoming</span> <span class="o">(</span><span class="n">next_var</span><span class="o">,</span> <span class="n">loop_end_bb</span><span class="o">)</span> <span class="n">variable</span><span class="o">;</span>
+
+ <span class="c">(* Restore the unshadowed variable. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">old_val</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">old_val</span> <span class="o">-></span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_val</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* for expr always returns 0.0. *)</span>
+ <span class="n">const_null</span> <span class="n">double_type</span>
+
+<span class="k">let</span> <span class="n">codegen_proto</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Make the function type: double(double,double) etc. *)</span>
+ <span class="k">let</span> <span class="n">doubles</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">make</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span><span class="o">)</span> <span class="n">double_type</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">ft</span> <span class="o">=</span> <span class="n">function_type</span> <span class="n">double_type</span> <span class="n">doubles</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">f</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">name</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">declare_function</span> <span class="n">name</span> <span class="n">ft</span> <span class="n">the_module</span>
+
+ <span class="c">(* If 'f' conflicted, there was already something named 'name'. If it</span>
+<span class="c"> * has a body, don't allow redefinition or reextern. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">f</span> <span class="o">-></span>
+ <span class="c">(* If 'f' already has a body, reject this. *)</span>
+ <span class="k">if</span> <span class="n">block_begin</span> <span class="n">f</span> <span class="o"><></span> <span class="nc">At_end</span> <span class="n">f</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function"</span><span class="o">);</span>
+
+ <span class="c">(* If 'f' took a different number of arguments, reject. *)</span>
+ <span class="k">if</span> <span class="n">element_type</span> <span class="o">(</span><span class="n">type_of</span> <span class="n">f</span><span class="o">)</span> <span class="o"><></span> <span class="n">ft</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function with different # args"</span><span class="o">);</span>
+ <span class="n">f</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Set names for all arguments. *)</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">a</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">n</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">set_value_name</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">f</span><span class="o">);</span>
+ <span class="n">f</span>
+
+<span class="k">let</span> <span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">proto</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">clear</span> <span class="n">named_values</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">codegen_proto</span> <span class="n">proto</span> <span class="k">in</span>
+
+ <span class="c">(* Create a new basic block to start insertion into. *)</span>
+ <span class="k">let</span> <span class="n">bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"entry"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="k">try</span>
+ <span class="k">let</span> <span class="n">ret_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+ <span class="c">(* Finish off the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="n">build_ret</span> <span class="n">ret_val</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Validate the generated code, checking for consistency. *)</span>
+ <span class="nn">Llvm_analysis</span><span class="p">.</span><span class="n">assert_valid_function</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* Optimize the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="n">the_fpm</span> <span class="k">in</span>
+
+ <span class="n">the_function</span>
+ <span class="k">with</span> <span class="n">e</span> <span class="o">-></span>
+ <span class="n">delete_function</span> <span class="n">the_function</span><span class="o">;</span>
+ <span class="k">raise</span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>toplevel.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Top-Level parsing and JIT Driver</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+
+<span class="c">(* top ::= definition | external | expression | ';' *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+
+ <span class="c">(* ignore top-level semicolons. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">';'</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">token</span> <span class="o">-></span>
+ <span class="k">begin</span>
+ <span class="k">try</span> <span class="k">match</span> <span class="n">token</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_definition</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a function definition."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_extern</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed an extern."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_proto</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* Evaluate a top-level expression into an anonymous function. *)</span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_toplevel</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a top-level expr"</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span> <span class="k">in</span>
+ <span class="n">dump_value</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* JIT the function, returning a function pointer. *)</span>
+ <span class="k">let</span> <span class="n">result</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="o">[||]</span>
+ <span class="n">the_execution_engine</span> <span class="k">in</span>
+
+ <span class="n">print_string</span> <span class="s2">"Evaluated to "</span><span class="o">;</span>
+ <span class="n">print_float</span> <span class="o">(</span><span class="nn">GenericValue</span><span class="p">.</span><span class="n">as_float</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">double_type</span> <span class="n">result</span><span class="o">);</span>
+ <span class="n">print_newline</span> <span class="bp">()</span><span class="o">;</span>
+ <span class="k">with</span> <span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">|</span> <span class="nn">Codegen</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">-></span>
+ <span class="c">(* Skip token for error recovery. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">print_endline</span> <span class="n">s</span><span class="o">;</span>
+ <span class="k">end</span><span class="o">;</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+</pre></div>
+</div>
+</dd>
+<dt>toy.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Main driver code.</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+<span class="k">open</span> <span class="nc">Llvm_target</span>
+<span class="k">open</span> <span class="nc">Llvm_scalar_opts</span>
+
+<span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">initialize_native_target</span> <span class="bp">()</span><span class="o">);</span>
+
+ <span class="c">(* Install standard binary operators.</span>
+<span class="c"> * 1 is the lowest precedence. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'*'</span> <span class="mi">40</span><span class="o">;</span> <span class="c">(* highest. *)</span>
+
+ <span class="c">(* Prime the first token. *)</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">stream</span> <span class="o">=</span> <span class="nn">Lexer</span><span class="p">.</span><span class="n">lex</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="n">of_channel</span> <span class="n">stdin</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Create the JIT. *)</span>
+ <span class="k">let</span> <span class="n">the_execution_engine</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">create</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+ <span class="c">(* Set up the optimizer pipeline. Start with registering info about how the</span>
+<span class="c"> * target lays out data structures. *)</span>
+ <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+ <span class="n">add_instruction_combination</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* reassociate expressions. *)</span>
+ <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Eliminate Common SubExpressions. *)</span>
+ <span class="n">add_gvn</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Simplify the control flow graph (deleting unreachable blocks, etc). *)</span>
+ <span class="n">add_cfg_simplification</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="n">ignore</span> <span class="o">(</span><span class="nn">PassManager</span><span class="p">.</span><span class="n">initialize</span> <span class="n">the_fpm</span><span class="o">);</span>
+
+ <span class="c">(* Run the main "interpreter loop" now. *)</span>
+ <span class="nn">Toplevel</span><span class="p">.</span><span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Print out all the generated code. *)</span>
+ <span class="n">dump_module</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span>
+<span class="o">;;</span>
+
+<span class="n">main</span> <span class="bp">()</span>
+</pre></div>
+</div>
+</dd>
+<dt>bindings.c</dt>
+<dd><div class="first last highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="cm">/* putchard - putchar that takes a double and returns 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">putchard</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">putchar</span><span class="p">((</span><span class="kt">char</span><span class="p">)</span><span class="n">X</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+<p><a class="reference external" href="OCamlLangImpl6.html">Next: Extending the language: user-defined
+operators</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl4.html" title="4. Kaleidoscope: Adding JIT and Optimizer Support"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl6.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl6.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl6.html (added)
+++ www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl6.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1485 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>6. Kaleidoscope: Extending the Language: User-defined Operators — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+ <link rel="next" title="7. Kaleidoscope: Extending the Language: Mutable Variables" href="OCamlLangImpl7.html" />
+ <link rel="prev" title="5. Kaleidoscope: Extending the Language: Control Flow" href="OCamlLangImpl5.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl5.html" title="5. Kaleidoscope: Extending the Language: Control Flow"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="kaleidoscope-extending-the-language-user-defined-operators">
+<h1>6. Kaleidoscope: Extending the Language: User-defined Operators<a class="headerlink" href="#kaleidoscope-extending-the-language-user-defined-operators" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#chapter-6-introduction" id="id1">Chapter 6 Introduction</a></li>
+<li><a class="reference internal" href="#user-defined-operators-the-idea" id="id2">User-defined Operators: the Idea</a></li>
+<li><a class="reference internal" href="#user-defined-binary-operators" id="id3">User-defined Binary Operators</a></li>
+<li><a class="reference internal" href="#user-defined-unary-operators" id="id4">User-defined Unary Operators</a></li>
+<li><a class="reference internal" href="#kicking-the-tires" id="id5">Kicking the Tires</a></li>
+<li><a class="reference internal" href="#full-code-listing" id="id6">Full Code Listing</a></li>
+</ul>
+</div>
+<div class="section" id="chapter-6-introduction">
+<h2><a class="toc-backref" href="#id1">6.1. Chapter 6 Introduction</a><a class="headerlink" href="#chapter-6-introduction" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to Chapter 6 of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. At this point in our tutorial, we now
+have a fully functional language that is fairly minimal, but also
+useful. There is still one big problem with it, however. Our language
+doesn’t have many useful operators (like division, logical negation, or
+even any comparisons besides less-than).</p>
+<p>This chapter of the tutorial takes a wild digression into adding
+user-defined operators to the simple and beautiful Kaleidoscope
+language. This digression now gives us a simple and ugly language in
+some ways, but also a powerful one at the same time. One of the great
+things about creating your own language is that you get to decide what
+is good or bad. In this tutorial we’ll assume that it is okay to use
+this as a way to show some interesting parsing techniques.</p>
+<p>At the end of this tutorial, we’ll run through an example Kaleidoscope
+application that <a class="reference external" href="#kicking-the-tires">renders the Mandelbrot set</a>. This gives an
+example of what you can build with Kaleidoscope and its feature set.</p>
+</div>
+<div class="section" id="user-defined-operators-the-idea">
+<h2><a class="toc-backref" href="#id2">6.2. User-defined Operators: the Idea</a><a class="headerlink" href="#user-defined-operators-the-idea" title="Permalink to this headline">¶</a></h2>
+<p>The “operator overloading” that we will add to Kaleidoscope is more
+general than languages like C++. In C++, you are only allowed to
+redefine existing operators: you can’t programmatically change the
+grammar, introduce new operators, change precedence levels, etc. In this
+chapter, we will add this capability to Kaleidoscope, which will let the
+user round out the set of operators that are supported.</p>
+<p>The point of going into user-defined operators in a tutorial like this
+is to show the power and flexibility of using a hand-written parser.
+Thus far, the parser we have been implementing uses recursive descent
+for most parts of the grammar and operator precedence parsing for the
+expressions. See <a class="reference external" href="OCamlLangImpl2.html">Chapter 2</a> for details. Without
+using operator precedence parsing, it would be very difficult to allow
+the programmer to introduce new operators into the grammar: the grammar
+is dynamically extensible as the JIT runs.</p>
+<p>The two specific features we’ll add are programmable unary operators
+(right now, Kaleidoscope has no unary operators at all) as well as
+binary operators. An example of this is:</p>
+<div class="highlight-python"><pre># Logical unary not.
+def unary!(v)
+ if v then
+ 0
+ else
+ 1;
+
+# Define > with the same precedence as <.
+def binary> 10 (LHS RHS)
+ RHS < LHS;
+
+# Binary "logical or", (note that it does not "short circuit")
+def binary| 5 (LHS RHS)
+ if LHS then
+ 1
+ else if RHS then
+ 1
+ else
+ 0;
+
+# Define = with slightly lower precedence than relationals.
+def binary= 9 (LHS RHS)
+ !(LHS < RHS | LHS > RHS);</pre>
+</div>
+<p>Many languages aspire to being able to implement their standard runtime
+library in the language itself. In Kaleidoscope, we can implement
+significant parts of the language in the library!</p>
+<p>We will break down implementation of these features into two parts:
+implementing support for user-defined binary operators and adding unary
+operators.</p>
+</div>
+<div class="section" id="user-defined-binary-operators">
+<h2><a class="toc-backref" href="#id3">6.3. User-defined Binary Operators</a><a class="headerlink" href="#user-defined-binary-operators" title="Permalink to this headline">¶</a></h2>
+<p>Adding support for user-defined binary operators is pretty simple with
+our current framework. We’ll first add support for the unary/binary
+keywords:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* operators *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="o">|</span> <span class="nn">Unary</span>
+
+<span class="p">...</span>
+
+<span class="n">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+</pre></div>
+</div>
+<p>This just adds lexer support for the unary and binary keywords, like we
+did in <a class="reference external" href="OCamlLangImpl5.html#lexer-extensions-for-if-then-else">previous chapters</a>. One nice
+thing about our current AST, is that we represent binary operators with
+full generalisation by using their ASCII code as the opcode. For our
+extended operators, we’ll use this same representation, so we don’t need
+any new AST or parser support.</p>
+<p>On the other hand, we have to be able to represent the definitions of
+these new operators, in the “def binary| 5” part of the function
+definition. In our grammar so far, the “name” for the function
+definition is parsed as the “prototype” production and into the
+<tt class="docutils literal"><span class="pre">Ast.Prototype</span></tt> AST node. To represent our new user-defined operators
+as prototypes, we have to extend the <tt class="docutils literal"><span class="pre">Ast.Prototype</span></tt> AST node like
+this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* proto - This type represents the "prototype" for a function, which captures</span>
+<span class="c"> * its name, and its argument names (thus implicitly the number of arguments the</span>
+<span class="c"> * function takes). *)</span>
+<span class="k">type</span> <span class="n">proto</span> <span class="o">=</span>
+ <span class="o">|</span> <span class="nc">Prototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span>
+ <span class="o">|</span> <span class="nc">BinOpPrototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span> <span class="o">*</span> <span class="kt">int</span>
+</pre></div>
+</div>
+<p>Basically, in addition to knowing a name for the prototype, we now keep
+track of whether it was an operator, and if it was, what precedence
+level the operator is at. The precedence is only used for binary
+operators (as you’ll see below, it just doesn’t apply for unary
+operators). Now that we have a way to represent the prototype for a
+user-defined operator, we need to parse it:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* prototype</span>
+<span class="c"> * ::= id '(' id* ')'</span>
+<span class="c"> * ::= binary LETTER number? (id, id)</span>
+<span class="c"> * ::= unary LETTER number? (id) *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_operator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"unary"</span><span class="o">,</span> <span class="mi">1</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"binary"</span><span class="o">,</span> <span class="mi">2</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_binary_precedence</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">int_of_float</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="mi">30</span>
+ <span class="k">in</span>
+ <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* success. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">(</span><span class="n">prefix</span><span class="o">,</span> <span class="n">kind</span><span class="o">)=</span><span class="n">parse_operator</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="o">??</span> <span class="s2">"expected an operator"</span><span class="o">;</span>
+ <span class="c">(* Read the precedence if present. *)</span>
+ <span class="n">binary_precedence</span><span class="o">=</span><span class="n">parse_binary_precedence</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span> <span class="n">prefix</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Verify right number of arguments for operator. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="o">!=</span> <span class="n">kind</span>
+ <span class="k">then</span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"invalid number of operands for operator"</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="k">if</span> <span class="n">kind</span> <span class="o">==</span> <span class="mi">1</span> <span class="k">then</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">binary_precedence</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+</pre></div>
+</div>
+<p>This is all fairly straightforward parsing code, and we have already
+seen a lot of similar code in the past. One interesting part about the
+code above is the couple lines that set up <tt class="docutils literal"><span class="pre">name</span></tt> for binary
+operators. This builds names like “binary@” for a newly defined “@”
+operator. This then takes advantage of the fact that symbol names in the
+LLVM symbol table are allowed to have any character in them, including
+embedded nul characters.</p>
+<p>The next interesting thing to add, is codegen support for these binary
+operators. Given our current structure, this is a simple addition of a
+default case for our existing binary operator node:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">lhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">lhs</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">rhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+ <span class="k">begin</span>
+ <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'+'</span> <span class="o">-></span> <span class="n">build_add</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"addtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'-'</span> <span class="o">-></span> <span class="n">build_sub</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"subtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'*'</span> <span class="o">-></span> <span class="n">build_mul</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"multmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'<'</span> <span class="o">-></span>
+ <span class="c">(* Convert bool 0/1 to double 0.0 or 1.0 *)</span>
+ <span class="k">let</span> <span class="n">i</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">Ult</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"cmptmp"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">build_uitofp</span> <span class="n">i</span> <span class="n">double_type</span> <span class="s2">"booltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* If it wasn't a builtin binary operator, it must be a user defined</span>
+<span class="c"> * one. Emit a call to it. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"binary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"binary operator not found!"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">lhs_val</span><span class="o">;</span> <span class="n">rhs_val</span><span class="o">|]</span> <span class="s2">"binop"</span> <span class="n">builder</span>
+ <span class="k">end</span>
+</pre></div>
+</div>
+<p>As you can see above, the new code is actually really simple. It just
+does a lookup for the appropriate operator in the symbol table and
+generates a function call to it. Since user-defined operators are just
+built as normal functions (because the “prototype” boils down to a
+function with the right name) everything falls into place.</p>
+<p>The final piece of code we are missing, is a bit of top level magic:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">proto</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">clear</span> <span class="n">named_values</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">codegen_proto</span> <span class="n">proto</span> <span class="k">in</span>
+
+ <span class="c">(* If this is an operator, install it. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">prec</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">op</span> <span class="o">=</span> <span class="n">name</span><span class="o">.[</span><span class="nn">String</span><span class="p">.</span><span class="n">length</span> <span class="n">name</span> <span class="o">-</span> <span class="mi">1</span><span class="o">]</span> <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="n">op</span> <span class="n">prec</span><span class="o">;</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* Create a new basic block to start insertion into. *)</span>
+ <span class="k">let</span> <span class="n">bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"entry"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>Basically, before codegening a function, if it is a user-defined
+operator, we register it in the precedence table. This allows the binary
+operator parsing logic we already have in place to handle it. Since we
+are working on a fully-general operator precedence parser, this is all
+we need to do to “extend the grammar”.</p>
+<p>Now we have useful user-defined binary operators. This builds a lot on
+the previous framework we built for other operators. Adding unary
+operators is a bit more challenging, because we don’t have any framework
+for it yet - lets see what it takes.</p>
+</div>
+<div class="section" id="user-defined-unary-operators">
+<h2><a class="toc-backref" href="#id4">6.4. User-defined Unary Operators</a><a class="headerlink" href="#user-defined-unary-operators" title="Permalink to this headline">¶</a></h2>
+<p>Since we don’t currently support unary operators in the Kaleidoscope
+language, we’ll need to add everything to support them. Above, we added
+simple support for the ‘unary’ keyword to the lexer. In addition to
+that, we need an AST node:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* variant for a unary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Unary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>This AST node is very simple and obvious by now. It directly mirrors the
+binary operator AST node, except that it only has one child. With this,
+we need to add the parsing logic. Parsing a unary operator is pretty
+simple: we’ll add a new function to do it:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* unary</span>
+<span class="c"> * ::= primary</span>
+<span class="c"> * ::= '!' unary *)</span>
+<span class="ow">and</span> <span class="n">parse_unary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* If this is a unary operator, read it. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="k">when</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">'('</span> <span class="o">&&</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">')'</span><span class="o">;</span> <span class="n">operand</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span>
+
+ <span class="c">(* If the current token is not an operator, it must be a primary expr. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_primary</span> <span class="n">stream</span>
+</pre></div>
+</div>
+<p>The grammar we add is pretty straightforward here. If we see a unary
+operator when parsing a primary operator, we eat the operator as a
+prefix and parse the remaining piece as another unary operator. This
+allows us to handle multiple unary operators (e.g. ”!!x”). Note that
+unary operators can’t have ambiguous parses like binary operators can,
+so there is no need for precedence information.</p>
+<p>The problem with this function, is that we need to call ParseUnary from
+somewhere. To do this, we change previous callers of ParsePrimary to
+call <tt class="docutils literal"><span class="pre">parse_unary</span></tt> instead:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* binoprhs</span>
+<span class="c"> * ::= ('+' primary)* *)</span>
+<span class="ow">and</span> <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* Parse the unary expression after the binary operator. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span> <span class="n">parse_unary</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="o">...</span>
+
+<span class="o">...</span>
+
+<span class="c">(* expression</span>
+<span class="c"> * ::= primary binoprhs *)</span>
+<span class="ow">and</span> <span class="n">parse_expr</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">lhs</span><span class="o">=</span><span class="n">parse_unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_bin_rhs</span> <span class="mi">0</span> <span class="n">lhs</span> <span class="n">stream</span>
+</pre></div>
+</div>
+<p>With these two simple changes, we are now able to parse unary operators
+and build the AST for them. Next up, we need to add parser support for
+prototypes, to parse the unary operator prototype. We extend the binary
+operator code above with:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* prototype</span>
+<span class="c"> * ::= id '(' id* ')'</span>
+<span class="c"> * ::= binary LETTER number? (id, id)</span>
+<span class="c"> * ::= unary LETTER number? (id) *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_operator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"unary"</span><span class="o">,</span> <span class="mi">1</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"binary"</span><span class="o">,</span> <span class="mi">2</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_binary_precedence</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">int_of_float</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="mi">30</span>
+ <span class="k">in</span>
+ <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* success. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">(</span><span class="n">prefix</span><span class="o">,</span> <span class="n">kind</span><span class="o">)=</span><span class="n">parse_operator</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="o">??</span> <span class="s2">"expected an operator"</span><span class="o">;</span>
+ <span class="c">(* Read the precedence if present. *)</span>
+ <span class="n">binary_precedence</span><span class="o">=</span><span class="n">parse_binary_precedence</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span> <span class="n">prefix</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Verify right number of arguments for operator. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="o">!=</span> <span class="n">kind</span>
+ <span class="k">then</span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"invalid number of operands for operator"</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="k">if</span> <span class="n">kind</span> <span class="o">==</span> <span class="mi">1</span> <span class="k">then</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">binary_precedence</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+</pre></div>
+</div>
+<p>As with binary operators, we name unary operators with a name that
+includes the operator character. This assists us at code generation
+time. Speaking of, the final piece we need to add is codegen support for
+unary operators. It looks like this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">operand</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">operand</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"unary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown unary operator"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">operand</span><span class="o">|]</span> <span class="s2">"unop"</span> <span class="n">builder</span>
+</pre></div>
+</div>
+<p>This code is similar to, but simpler than, the code for binary
+operators. It is simpler primarily because it doesn’t need to handle any
+predefined operators.</p>
+</div>
+<div class="section" id="kicking-the-tires">
+<h2><a class="toc-backref" href="#id5">6.5. Kicking the Tires</a><a class="headerlink" href="#kicking-the-tires" title="Permalink to this headline">¶</a></h2>
+<p>It is somewhat hard to believe, but with a few simple extensions we’ve
+covered in the last chapters, we have grown a real-ish language. With
+this, we can do a lot of interesting things, including I/O, math, and a
+bunch of other things. For example, we can now add a nice sequencing
+operator (printd is defined to print out the specified value and a
+newline):</p>
+<div class="highlight-python"><pre>ready> extern printd(x);
+Read extern: declare double @printd(double)
+ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
+..
+ready> printd(123) : printd(456) : printd(789);
+123.000000
+456.000000
+789.000000
+Evaluated to 0.000000</pre>
+</div>
+<p>We can also define a bunch of other “primitive” operations, such as:</p>
+<div class="highlight-python"><pre># Logical unary not.
+def unary!(v)
+ if v then
+ 0
+ else
+ 1;
+
+# Unary negate.
+def unary-(v)
+ 0-v;
+
+# Define > with the same precedence as <.
+def binary> 10 (LHS RHS)
+ RHS < LHS;
+
+# Binary logical or, which does not short circuit.
+def binary| 5 (LHS RHS)
+ if LHS then
+ 1
+ else if RHS then
+ 1
+ else
+ 0;
+
+# Binary logical and, which does not short circuit.
+def binary& 6 (LHS RHS)
+ if !LHS then
+ 0
+ else
+ !!RHS;
+
+# Define = with slightly lower precedence than relationals.
+def binary = 9 (LHS RHS)
+ !(LHS < RHS | LHS > RHS);</pre>
+</div>
+<p>Given the previous if/then/else support, we can also define interesting
+functions for I/O. For example, the following prints out a character
+whose “density” reflects the value passed in: the lower the value, the
+denser the character:</p>
+<div class="highlight-python"><pre>ready>
+
+extern putchard(char)
+def printdensity(d)
+ if d > 8 then
+ putchard(32) # ' '
+ else if d > 4 then
+ putchard(46) # '.'
+ else if d > 2 then
+ putchard(43) # '+'
+ else
+ putchard(42); # '*'
+...
+ready> printdensity(1): printdensity(2): printdensity(3) :
+ printdensity(4): printdensity(5): printdensity(9): putchard(10);
+*++..
+Evaluated to 0.000000</pre>
+</div>
+<p>Based on these simple primitive operations, we can start to define more
+interesting things. For example, here’s a little function that solves
+for the number of iterations it takes a function in the complex plane to
+converge:</p>
+<div class="highlight-python"><pre># determine whether the specific location diverges.
+# Solve for z = z^2 + c in the complex plane.
+def mandelconverger(real imag iters creal cimag)
+ if iters > 255 | (real*real + imag*imag > 4) then
+ iters
+ else
+ mandelconverger(real*real - imag*imag + creal,
+ 2*real*imag + cimag,
+ iters+1, creal, cimag);
+
+# return the number of iterations required for the iteration to escape
+def mandelconverge(real imag)
+ mandelconverger(real, imag, 0, real, imag);</pre>
+</div>
+<p>This “z = z<sup>2</sup> + c” function is a beautiful little creature
+that is the basis for computation of the <a class="reference external" href="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot
+Set</a>. Our
+<tt class="docutils literal"><span class="pre">mandelconverge</span></tt> function returns the number of iterations that it
+takes for a complex orbit to escape, saturating to 255. This is not a
+very useful function by itself, but if you plot its value over a
+two-dimensional plane, you can see the Mandelbrot set. Given that we are
+limited to using putchard here, our amazing graphical output is limited,
+but we can whip together something using the density plotter above:</p>
+<div class="highlight-python"><pre># compute and plot the mandelbrot set with the specified 2 dimensional range
+# info.
+def mandelhelp(xmin xmax xstep ymin ymax ystep)
+ for y = ymin, y < ymax, ystep in (
+ (for x = xmin, x < xmax, xstep in
+ printdensity(mandelconverge(x,y)))
+ : putchard(10)
+ )
+
+# mandel - This is a convenient helper function for plotting the mandelbrot set
+# from the specified position with the specified Magnification.
+def mandel(realstart imagstart realmag imagmag)
+ mandelhelp(realstart, realstart+realmag*78, realmag,
+ imagstart, imagstart+imagmag*40, imagmag);</pre>
+</div>
+<p>Given this, we can try plotting out the mandelbrot set! Lets try it out:</p>
+<div class="highlight-python"><pre>ready> mandel(-2.3, -1.3, 0.05, 0.07);
+*******************************+++++++++++*************************************
+*************************+++++++++++++++++++++++*******************************
+**********************+++++++++++++++++++++++++++++****************************
+*******************+++++++++++++++++++++.. ...++++++++*************************
+*****************++++++++++++++++++++++.... ...+++++++++***********************
+***************+++++++++++++++++++++++..... ...+++++++++*********************
+**************+++++++++++++++++++++++.... ....+++++++++********************
+*************++++++++++++++++++++++...... .....++++++++*******************
+************+++++++++++++++++++++....... .......+++++++******************
+***********+++++++++++++++++++.... ... .+++++++*****************
+**********+++++++++++++++++....... .+++++++****************
+*********++++++++++++++........... ...+++++++***************
+********++++++++++++............ ...++++++++**************
+********++++++++++... .......... .++++++++**************
+*******+++++++++..... .+++++++++*************
+*******++++++++...... ..+++++++++*************
+*******++++++....... ..+++++++++*************
+*******+++++...... ..+++++++++*************
+*******.... .... ...+++++++++*************
+*******.... . ...+++++++++*************
+*******+++++...... ...+++++++++*************
+*******++++++....... ..+++++++++*************
+*******++++++++...... .+++++++++*************
+*******+++++++++..... ..+++++++++*************
+********++++++++++... .......... .++++++++**************
+********++++++++++++............ ...++++++++**************
+*********++++++++++++++.......... ...+++++++***************
+**********++++++++++++++++........ .+++++++****************
+**********++++++++++++++++++++.... ... ..+++++++****************
+***********++++++++++++++++++++++....... .......++++++++*****************
+************+++++++++++++++++++++++...... ......++++++++******************
+**************+++++++++++++++++++++++.... ....++++++++********************
+***************+++++++++++++++++++++++..... ...+++++++++*********************
+*****************++++++++++++++++++++++.... ...++++++++***********************
+*******************+++++++++++++++++++++......++++++++*************************
+*********************++++++++++++++++++++++.++++++++***************************
+*************************+++++++++++++++++++++++*******************************
+******************************+++++++++++++************************************
+*******************************************************************************
+*******************************************************************************
+*******************************************************************************
+Evaluated to 0.000000
+ready> mandel(-2, -1, 0.02, 0.04);
+**************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
+***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+*********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
+*******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
+*****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
+***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
+**************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
+************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
+***********++++++++++++++++++++++++++++++++++++++++++++++++++........ .
+**********++++++++++++++++++++++++++++++++++++++++++++++.............
+********+++++++++++++++++++++++++++++++++++++++++++..................
+*******+++++++++++++++++++++++++++++++++++++++.......................
+******+++++++++++++++++++++++++++++++++++...........................
+*****++++++++++++++++++++++++++++++++............................
+*****++++++++++++++++++++++++++++...............................
+****++++++++++++++++++++++++++...... .........................
+***++++++++++++++++++++++++......... ...... ...........
+***++++++++++++++++++++++............
+**+++++++++++++++++++++..............
+**+++++++++++++++++++................
+*++++++++++++++++++.................
+*++++++++++++++++............ ...
+*++++++++++++++..............
+*+++....++++................
+*.......... ...........
+*
+*.......... ...........
+*+++....++++................
+*++++++++++++++..............
+*++++++++++++++++............ ...
+*++++++++++++++++++.................
+**+++++++++++++++++++................
+**+++++++++++++++++++++..............
+***++++++++++++++++++++++............
+***++++++++++++++++++++++++......... ...... ...........
+****++++++++++++++++++++++++++...... .........................
+*****++++++++++++++++++++++++++++...............................
+*****++++++++++++++++++++++++++++++++............................
+******+++++++++++++++++++++++++++++++++++...........................
+*******+++++++++++++++++++++++++++++++++++++++.......................
+********+++++++++++++++++++++++++++++++++++++++++++..................
+Evaluated to 0.000000
+ready> mandel(-0.9, -1.4, 0.02, 0.03);
+*******************************************************************************
+*******************************************************************************
+*******************************************************************************
+**********+++++++++++++++++++++************************************************
+*+++++++++++++++++++++++++++++++++++++++***************************************
++++++++++++++++++++++++++++++++++++++++++++++**********************************
+++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
+++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
++++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
++++++++++++++++++++++++++++++++.... ......+++++++++++++++++++****************
++++++++++++++++++++++++++++++....... ........+++++++++++++++++++**************
+++++++++++++++++++++++++++++........ ........++++++++++++++++++++************
++++++++++++++++++++++++++++......... .. ...+++++++++++++++++++++**********
+++++++++++++++++++++++++++........... ....++++++++++++++++++++++********
+++++++++++++++++++++++++............. .......++++++++++++++++++++++******
++++++++++++++++++++++++............. ........+++++++++++++++++++++++****
+++++++++++++++++++++++........... ..........++++++++++++++++++++++***
+++++++++++++++++++++........... .........++++++++++++++++++++++*
+++++++++++++++++++............ ...........++++++++++++++++++++
+++++++++++++++++............... .............++++++++++++++++++
+++++++++++++++................. ...............++++++++++++++++
+++++++++++++.................. .................++++++++++++++
++++++++++.................. .................+++++++++++++
+++++++........ . ......... ..++++++++++++
+++............ ...... ....++++++++++
+.............. ...++++++++++
+.............. ....+++++++++
+.............. .....++++++++
+............. ......++++++++
+........... .......++++++++
+......... ........+++++++
+......... ........+++++++
+......... ....+++++++
+........ ...+++++++
+....... ...+++++++
+ ....+++++++
+ .....+++++++
+ ....+++++++
+ ....+++++++
+ ....+++++++
+Evaluated to 0.000000
+ready> ^D</pre>
+</div>
+<p>At this point, you may be starting to realize that Kaleidoscope is a
+real and powerful language. It may not be self-similar :), but it can be
+used to plot things that are!</p>
+<p>With this, we conclude the “adding user-defined operators” chapter of
+the tutorial. We have successfully augmented our language, adding the
+ability to extend the language in the library, and we have shown how
+this can be used to build a simple but interesting end-user application
+in Kaleidoscope. At this point, Kaleidoscope can build a variety of
+applications that are functional and can call functions with
+side-effects, but it can’t actually define and mutate a variable itself.</p>
+<p>Strikingly, variable mutation is an important feature of some languages,
+and it is not at all obvious how to <a class="reference external" href="OCamlLangImpl7.html">add support for mutable
+variables</a> without having to add an “SSA
+construction” phase to your front-end. In the next chapter, we will
+describe how you can add variable mutation without building SSA in your
+front-end.</p>
+</div>
+<div class="section" id="full-code-listing">
+<h2><a class="toc-backref" href="#id6">6.6. Full Code Listing</a><a class="headerlink" href="#full-code-listing" title="Permalink to this headline">¶</a></h2>
+<p>Here is the complete code listing for our running example, enhanced with
+the if/then/else and for expressions.. To build this example, use:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Compile</span>
+ocamlbuild toy.byte
+<span class="c"># Run</span>
+./toy.byte
+</pre></div>
+</div>
+<p>Here is the code:</p>
+<dl class="docutils">
+<dt>_tags:</dt>
+<dd><div class="first last highlight-python"><pre><{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
+<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
+<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
+<*.{byte,native}>: use_llvm_scalar_opts, use_bindings</pre>
+</div>
+</dd>
+<dt>myocamlbuild.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="k">open</span> <span class="nc">Ocamlbuild_plugin</span><span class="o">;;</span>
+
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_analysis"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_executionengine"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_target"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_scalar_opts"</span><span class="o">;;</span>
+
+<span class="n">flag</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"g++"</span><span class="o">]</span> <span class="o">(</span><span class="nc">S</span><span class="o">[</span><span class="nc">A</span><span class="s2">"-cc"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"g++"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-cclib"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-rdynamic"</span><span class="o">]);;</span>
+<span class="n">dep</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"use_bindings"</span><span class="o">]</span> <span class="o">[</span><span class="s2">"bindings.o"</span><span class="o">];;</span>
+</pre></div>
+</div>
+</dd>
+<dt>token.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer Tokens</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of</span>
+<span class="c"> * these others for known things. *)</span>
+<span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+ <span class="c">(* commands *)</span>
+ <span class="o">|</span> <span class="nc">Def</span> <span class="o">|</span> <span class="nc">Extern</span>
+
+ <span class="c">(* primary *)</span>
+ <span class="o">|</span> <span class="nc">Ident</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* unknown *)</span>
+ <span class="o">|</span> <span class="nc">Kwd</span> <span class="k">of</span> <span class="kt">char</span>
+
+ <span class="c">(* control *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nc">In</span>
+
+ <span class="c">(* operators *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="o">|</span> <span class="nc">Unary</span>
+</pre></div>
+</div>
+</dd>
+<dt>lexer.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">lex</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Skip any whitespace. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">' '</span> <span class="o">|</span> <span class="sc">'\n'</span> <span class="o">|</span> <span class="sc">'\r'</span> <span class="o">|</span> <span class="sc">'\t'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">lex</span> <span class="n">stream</span>
+
+ <span class="c">(* identifier: [a-zA-Z][a-zA-Z0-9] *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* number: [0-9.]+ *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* Comment until end of line. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'#'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="n">lex_comment</span> <span class="n">stream</span>
+
+ <span class="c">(* Otherwise, just return the character as its ascii value. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">;</span> <span class="n">lex</span> <span class="n">stream</span> <span class="o">>]</span>
+
+ <span class="c">(* end of stream. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_number</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="o">|</span> <span class="sc">'.'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="o">(</span><span class="n">float_of_string</span> <span class="o">(</span><span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span><span class="o">));</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="o">|</span> <span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_comment</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'\n'</span><span class="o">);</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">lex_comment</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</dd>
+<dt>ast.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Abstract Syntax Tree (aka Parse Tree)</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* expr - Base type for all expression nodes. *)</span>
+<span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="c">(* variant for numeric literals like "1.0". *)</span>
+ <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* variant for referencing a variable, like "a". *)</span>
+ <span class="o">|</span> <span class="nc">Variable</span> <span class="k">of</span> <span class="kt">string</span>
+
+ <span class="c">(* variant for a unary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Unary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for a binary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for function calls. *)</span>
+ <span class="o">|</span> <span class="nc">Call</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="kt">array</span>
+
+ <span class="c">(* variant for if/then/else. *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="k">of</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for for/in. *)</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span> <span class="o">*</span> <span class="n">expr</span>
+
+<span class="c">(* proto - This type represents the "prototype" for a function, which captures</span>
+<span class="c"> * its name, and its argument names (thus implicitly the number of arguments the</span>
+<span class="c"> * function takes). *)</span>
+<span class="k">type</span> <span class="n">proto</span> <span class="o">=</span>
+ <span class="o">|</span> <span class="nc">Prototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span>
+ <span class="o">|</span> <span class="nc">BinOpPrototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span> <span class="o">*</span> <span class="kt">int</span>
+
+<span class="c">(* func - This type represents a function definition itself. *)</span>
+<span class="k">type</span> <span class="n">func</span> <span class="o">=</span> <span class="nc">Function</span> <span class="k">of</span> <span class="n">proto</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+</dd>
+<dt>parser.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===---------------------------------------------------------------------===</span>
+<span class="c"> * Parser</span>
+<span class="c"> *===---------------------------------------------------------------------===*)</span>
+
+<span class="c">(* binop_precedence - This holds the precedence for each binary operator that is</span>
+<span class="c"> * defined *)</span>
+<span class="k">let</span> <span class="n">binop_precedence</span><span class="o">:(</span><span class="kt">char</span><span class="o">,</span> <span class="kt">int</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+
+<span class="c">(* precedence - Get the precedence of the pending binary operator token. *)</span>
+<span class="k">let</span> <span class="n">precedence</span> <span class="n">c</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="o">-</span><span class="mi">1</span>
+
+<span class="c">(* primary</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= numberexpr</span>
+<span class="c"> * ::= parenexpr</span>
+<span class="c"> * ::= ifexpr</span>
+<span class="c"> * ::= forexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* numberexpr ::= number *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span>
+
+ <span class="c">(* parenexpr ::= '(' expression ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+
+ <span class="c">(* identifierexpr</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= identifier '(' argumentexpr ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_ident</span> <span class="n">id</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Call. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span><span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+
+ <span class="c">(* Simple variable ref. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">id</span>
+ <span class="k">in</span>
+ <span class="n">parse_ident</span> <span class="n">id</span> <span class="n">stream</span>
+
+ <span class="c">(* ifexpr ::= 'if' expr 'then' expr 'else' expr *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">c</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span> <span class="o">??</span> <span class="s2">"expected 'then'"</span><span class="o">;</span> <span class="n">t</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span> <span class="o">??</span> <span class="s2">"expected 'else'"</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">t</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+ <span class="c">(* forexpr</span>
+<span class="c"> ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after for"</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span> <span class="o">??</span> <span class="s2">"expected '=' after for"</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span>
+ <span class="n">start</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span> <span class="o">??</span> <span class="s2">"expected ',' after for"</span><span class="o">;</span>
+ <span class="n">end_</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">step</span> <span class="o">=</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">step</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">step</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="k">in</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected 'in' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected '=' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"unknown token when expecting an expression."</span><span class="o">)</span>
+
+<span class="c">(* unary</span>
+<span class="c"> * ::= primary</span>
+<span class="c"> * ::= '!' unary *)</span>
+<span class="ow">and</span> <span class="n">parse_unary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* If this is a unary operator, read it. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="k">when</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">'('</span> <span class="o">&&</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">')'</span><span class="o">;</span> <span class="n">operand</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span>
+
+ <span class="c">(* If the current token is not an operator, it must be a primary expr. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_primary</span> <span class="n">stream</span>
+
+<span class="c">(* binoprhs</span>
+<span class="c"> * ::= ('+' primary)* *)</span>
+<span class="ow">and</span> <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="c">(* If this is a binop, find its precedence. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">)</span> <span class="k">when</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">mem</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">token_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c</span> <span class="k">in</span>
+
+ <span class="c">(* If this is a binop that binds at least as tightly as the current binop,</span>
+<span class="c"> * consume it, otherwise we are done. *)</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">expr_prec</span> <span class="k">then</span> <span class="n">lhs</span> <span class="k">else</span> <span class="k">begin</span>
+ <span class="c">(* Eat the binop. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Parse the unary expression after the binary operator. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span> <span class="n">parse_unary</span> <span class="n">stream</span> <span class="k">in</span>
+
+ <span class="c">(* Okay, we know this is a binop. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c2</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* If BinOp binds less tightly with rhs than the operator after</span>
+<span class="c"> * rhs, let the pending operator take rhs as its lhs. *)</span>
+ <span class="k">let</span> <span class="n">next_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c2</span> <span class="k">in</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">next_prec</span>
+ <span class="k">then</span> <span class="n">parse_bin_rhs</span> <span class="o">(</span><span class="n">token_prec</span> <span class="o">+</span> <span class="mi">1</span><span class="o">)</span> <span class="n">rhs</span> <span class="n">stream</span>
+ <span class="k">else</span> <span class="n">rhs</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">rhs</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Merge lhs/rhs. *)</span>
+ <span class="k">let</span> <span class="n">lhs</span> <span class="o">=</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">lhs</span>
+
+<span class="c">(* expression</span>
+<span class="c"> * ::= primary binoprhs *)</span>
+<span class="ow">and</span> <span class="n">parse_expr</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">lhs</span><span class="o">=</span><span class="n">parse_unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_bin_rhs</span> <span class="mi">0</span> <span class="n">lhs</span> <span class="n">stream</span>
+
+<span class="c">(* prototype</span>
+<span class="c"> * ::= id '(' id* ')'</span>
+<span class="c"> * ::= binary LETTER number? (id, id)</span>
+<span class="c"> * ::= unary LETTER number? (id) *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_operator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"unary"</span><span class="o">,</span> <span class="mi">1</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"binary"</span><span class="o">,</span> <span class="mi">2</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_binary_precedence</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">int_of_float</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="mi">30</span>
+ <span class="k">in</span>
+ <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* success. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">(</span><span class="n">prefix</span><span class="o">,</span> <span class="n">kind</span><span class="o">)=</span><span class="n">parse_operator</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="o">??</span> <span class="s2">"expected an operator"</span><span class="o">;</span>
+ <span class="c">(* Read the precedence if present. *)</span>
+ <span class="n">binary_precedence</span><span class="o">=</span><span class="n">parse_binary_precedence</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span> <span class="n">prefix</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Verify right number of arguments for operator. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="o">!=</span> <span class="n">kind</span>
+ <span class="k">then</span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"invalid number of operands for operator"</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="k">if</span> <span class="n">kind</span> <span class="o">==</span> <span class="mi">1</span> <span class="k">then</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">binary_precedence</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+
+<span class="c">(* definition ::= 'def' prototype expression *)</span>
+<span class="k">let</span> <span class="n">parse_definition</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">p</span><span class="o">=</span><span class="n">parse_prototype</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">p</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* toplevelexpr ::= expression *)</span>
+<span class="k">let</span> <span class="n">parse_toplevel</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* Make an anonymous proto. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="s2">""</span><span class="o">,</span> <span class="o">[||]),</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* external ::= 'extern' prototype *)</span>
+<span class="k">let</span> <span class="n">parse_extern</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_prototype</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>codegen.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Code Generation</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+
+<span class="k">exception</span> <span class="nc">Error</span> <span class="k">of</span> <span class="kt">string</span>
+
+<span class="k">let</span> <span class="n">context</span> <span class="o">=</span> <span class="n">global_context</span> <span class="bp">()</span>
+<span class="k">let</span> <span class="n">the_module</span> <span class="o">=</span> <span class="n">create_module</span> <span class="n">context</span> <span class="s2">"my cool jit"</span>
+<span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span> <span class="n">context</span>
+<span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+<span class="k">let</span> <span class="n">double_type</span> <span class="o">=</span> <span class="n">double_type</span> <span class="n">context</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+ <span class="o">(</span><span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">))</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">operand</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">operand</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"unary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown unary operator"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">operand</span><span class="o">|]</span> <span class="s2">"unop"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">lhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">lhs</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">rhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+ <span class="k">begin</span>
+ <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'+'</span> <span class="o">-></span> <span class="n">build_add</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"addtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'-'</span> <span class="o">-></span> <span class="n">build_sub</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"subtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'*'</span> <span class="o">-></span> <span class="n">build_mul</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"multmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'<'</span> <span class="o">-></span>
+ <span class="c">(* Convert bool 0/1 to double 0.0 or 1.0 *)</span>
+ <span class="k">let</span> <span class="n">i</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">Ult</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"cmptmp"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">build_uitofp</span> <span class="n">i</span> <span class="n">double_type</span> <span class="s2">"booltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* If it wasn't a builtin binary operator, it must be a user defined</span>
+<span class="c"> * one. Emit a call to it. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"binary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"binary operator not found!"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">lhs_val</span><span class="o">;</span> <span class="n">rhs_val</span><span class="o">|]</span> <span class="s2">"binop"</span> <span class="n">builder</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">callee</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Look up the name in the module table. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown function referenced"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="n">callee</span> <span class="k">in</span>
+
+ <span class="c">(* If argument mismatch error. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">params</span> <span class="o">==</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="k">then</span> <span class="bp">()</span> <span class="k">else</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"incorrect # arguments passed"</span><span class="o">);</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">map</span> <span class="n">codegen_expr</span> <span class="n">args</span> <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="n">args</span> <span class="s2">"calltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">cond</span><span class="o">,</span> <span class="n">then_</span><span class="o">,</span> <span class="n">else_</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">cond</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0 *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">cond_val</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">cond</span> <span class="n">zero</span> <span class="s2">"ifcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Grab the first block so that we might later add the conditional branch</span>
+<span class="c"> * to it at the end of the function. *)</span>
+ <span class="k">let</span> <span class="n">start_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">start_bb</span> <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">then_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"then"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'then' value. *)</span>
+ <span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">then_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">then_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'then' can change the current block, update then_bb for the</span>
+<span class="c"> * phi. We create a new name because one is used for the phi node, and the</span>
+<span class="c"> * other is used for the conditional branch. *)</span>
+ <span class="k">let</span> <span class="n">new_then_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'else' value. *)</span>
+ <span class="k">let</span> <span class="n">else_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"else"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">else_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">else_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'else' can change the current block, update else_bb for the</span>
+<span class="c"> * phi. *)</span>
+ <span class="k">let</span> <span class="n">new_else_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit merge block. *)</span>
+ <span class="k">let</span> <span class="n">merge_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"ifcont"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">incoming</span> <span class="o">=</span> <span class="o">[(</span><span class="n">then_val</span><span class="o">,</span> <span class="n">new_then_bb</span><span class="o">);</span> <span class="o">(</span><span class="n">else_val</span><span class="o">,</span> <span class="n">new_else_bb</span><span class="o">)]</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">phi</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="n">incoming</span> <span class="s2">"iftmp"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Return to the start block to add the conditional branch. *)</span>
+ <span class="n">position_at_end</span> <span class="n">start_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">cond_val</span> <span class="n">then_bb</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Set a unconditional branch at the end of the 'then' block and the</span>
+<span class="c"> * 'else' block to the 'merge' block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">new_then_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="n">position_at_end</span> <span class="n">new_else_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Finally, set the builder to the end of the merge block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="n">phi</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+ <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+ <span class="c">(* Make the new basic block for the loop header, inserting after current</span>
+<span class="c"> * block. *)</span>
+ <span class="k">let</span> <span class="n">preheader_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">preheader_bb</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">loop_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"loop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert an explicit fall through from the current block to the</span>
+<span class="c"> * loop_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Start insertion in loop_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Start the PHI node with an entry for start. *)</span>
+ <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="o">[(</span><span class="n">start_val</span><span class="o">,</span> <span class="n">preheader_bb</span><span class="o">)]</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c"> * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c"> * now. *)</span>
+ <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+ <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">variable</span><span class="o">;</span>
+
+ <span class="c">(* Emit the body of the loop. This, like any other expr, can change the</span>
+<span class="c"> * current BB. Note that we ignore the value computed by the body, but</span>
+<span class="c"> * don't allow an error *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">codegen_expr</span> <span class="n">body</span><span class="o">);</span>
+
+ <span class="c">(* Emit the step value. *)</span>
+ <span class="k">let</span> <span class="n">step_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">step</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">step</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">step</span>
+ <span class="c">(* If not specified, use 1.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">1</span><span class="o">.</span><span class="mi">0</span>
+ <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">variable</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Compute the end condition. *)</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0. *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">end_cond</span> <span class="n">zero</span> <span class="s2">"loopcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Create the "after loop" block and insert it. *)</span>
+ <span class="k">let</span> <span class="n">loop_end_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">after_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"afterloop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert the conditional branch into the end of loop_end_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">end_cond</span> <span class="n">loop_bb</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Any new code will be inserted in after_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Add a new entry to the PHI node for the backedge. *)</span>
+ <span class="n">add_incoming</span> <span class="o">(</span><span class="n">next_var</span><span class="o">,</span> <span class="n">loop_end_bb</span><span class="o">)</span> <span class="n">variable</span><span class="o">;</span>
+
+ <span class="c">(* Restore the unshadowed variable. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">old_val</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">old_val</span> <span class="o">-></span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_val</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* for expr always returns 0.0. *)</span>
+ <span class="n">const_null</span> <span class="n">double_type</span>
+
+<span class="k">let</span> <span class="n">codegen_proto</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span>
+ <span class="c">(* Make the function type: double(double,double) etc. *)</span>
+ <span class="k">let</span> <span class="n">doubles</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">make</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span><span class="o">)</span> <span class="n">double_type</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">ft</span> <span class="o">=</span> <span class="n">function_type</span> <span class="n">double_type</span> <span class="n">doubles</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">f</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">name</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">declare_function</span> <span class="n">name</span> <span class="n">ft</span> <span class="n">the_module</span>
+
+ <span class="c">(* If 'f' conflicted, there was already something named 'name'. If it</span>
+<span class="c"> * has a body, don't allow redefinition or reextern. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">f</span> <span class="o">-></span>
+ <span class="c">(* If 'f' already has a body, reject this. *)</span>
+ <span class="k">if</span> <span class="n">block_begin</span> <span class="n">f</span> <span class="o"><></span> <span class="nc">At_end</span> <span class="n">f</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function"</span><span class="o">);</span>
+
+ <span class="c">(* If 'f' took a different number of arguments, reject. *)</span>
+ <span class="k">if</span> <span class="n">element_type</span> <span class="o">(</span><span class="n">type_of</span> <span class="n">f</span><span class="o">)</span> <span class="o"><></span> <span class="n">ft</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function with different # args"</span><span class="o">);</span>
+ <span class="n">f</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Set names for all arguments. *)</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">a</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">n</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">set_value_name</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">f</span><span class="o">);</span>
+ <span class="n">f</span>
+
+<span class="k">let</span> <span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">proto</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">clear</span> <span class="n">named_values</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">codegen_proto</span> <span class="n">proto</span> <span class="k">in</span>
+
+ <span class="c">(* If this is an operator, install it. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">prec</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">op</span> <span class="o">=</span> <span class="n">name</span><span class="o">.[</span><span class="nn">String</span><span class="p">.</span><span class="n">length</span> <span class="n">name</span> <span class="o">-</span> <span class="mi">1</span><span class="o">]</span> <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="n">op</span> <span class="n">prec</span><span class="o">;</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* Create a new basic block to start insertion into. *)</span>
+ <span class="k">let</span> <span class="n">bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"entry"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="k">try</span>
+ <span class="k">let</span> <span class="n">ret_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+ <span class="c">(* Finish off the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="n">build_ret</span> <span class="n">ret_val</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Validate the generated code, checking for consistency. *)</span>
+ <span class="nn">Llvm_analysis</span><span class="p">.</span><span class="n">assert_valid_function</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* Optimize the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="n">the_fpm</span> <span class="k">in</span>
+
+ <span class="n">the_function</span>
+ <span class="k">with</span> <span class="n">e</span> <span class="o">-></span>
+ <span class="n">delete_function</span> <span class="n">the_function</span><span class="o">;</span>
+ <span class="k">raise</span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>toplevel.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Top-Level parsing and JIT Driver</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+
+<span class="c">(* top ::= definition | external | expression | ';' *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+
+ <span class="c">(* ignore top-level semicolons. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">';'</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">token</span> <span class="o">-></span>
+ <span class="k">begin</span>
+ <span class="k">try</span> <span class="k">match</span> <span class="n">token</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_definition</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a function definition."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_extern</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed an extern."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_proto</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* Evaluate a top-level expression into an anonymous function. *)</span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_toplevel</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a top-level expr"</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span> <span class="k">in</span>
+ <span class="n">dump_value</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* JIT the function, returning a function pointer. *)</span>
+ <span class="k">let</span> <span class="n">result</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="o">[||]</span>
+ <span class="n">the_execution_engine</span> <span class="k">in</span>
+
+ <span class="n">print_string</span> <span class="s2">"Evaluated to "</span><span class="o">;</span>
+ <span class="n">print_float</span> <span class="o">(</span><span class="nn">GenericValue</span><span class="p">.</span><span class="n">as_float</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">double_type</span> <span class="n">result</span><span class="o">);</span>
+ <span class="n">print_newline</span> <span class="bp">()</span><span class="o">;</span>
+ <span class="k">with</span> <span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">|</span> <span class="nn">Codegen</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">-></span>
+ <span class="c">(* Skip token for error recovery. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">print_endline</span> <span class="n">s</span><span class="o">;</span>
+ <span class="k">end</span><span class="o">;</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+</pre></div>
+</div>
+</dd>
+<dt>toy.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Main driver code.</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+<span class="k">open</span> <span class="nc">Llvm_target</span>
+<span class="k">open</span> <span class="nc">Llvm_scalar_opts</span>
+
+<span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">initialize_native_target</span> <span class="bp">()</span><span class="o">);</span>
+
+ <span class="c">(* Install standard binary operators.</span>
+<span class="c"> * 1 is the lowest precedence. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'*'</span> <span class="mi">40</span><span class="o">;</span> <span class="c">(* highest. *)</span>
+
+ <span class="c">(* Prime the first token. *)</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">stream</span> <span class="o">=</span> <span class="nn">Lexer</span><span class="p">.</span><span class="n">lex</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="n">of_channel</span> <span class="n">stdin</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Create the JIT. *)</span>
+ <span class="k">let</span> <span class="n">the_execution_engine</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">create</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+ <span class="c">(* Set up the optimizer pipeline. Start with registering info about how the</span>
+<span class="c"> * target lays out data structures. *)</span>
+ <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+ <span class="n">add_instruction_combination</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* reassociate expressions. *)</span>
+ <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Eliminate Common SubExpressions. *)</span>
+ <span class="n">add_gvn</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Simplify the control flow graph (deleting unreachable blocks, etc). *)</span>
+ <span class="n">add_cfg_simplification</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="n">ignore</span> <span class="o">(</span><span class="nn">PassManager</span><span class="p">.</span><span class="n">initialize</span> <span class="n">the_fpm</span><span class="o">);</span>
+
+ <span class="c">(* Run the main "interpreter loop" now. *)</span>
+ <span class="nn">Toplevel</span><span class="p">.</span><span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Print out all the generated code. *)</span>
+ <span class="n">dump_module</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span>
+<span class="o">;;</span>
+
+<span class="n">main</span> <span class="bp">()</span>
+</pre></div>
+</div>
+</dd>
+<dt>bindings.c</dt>
+<dd><div class="first last highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="cm">/* putchard - putchar that takes a double and returns 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">putchard</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">putchar</span><span class="p">((</span><span class="kt">char</span><span class="p">)</span><span class="n">X</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="cm">/* printd - printf that takes a double prints it as "%f\n", returning 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">printd</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"%f</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">X</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+<p><a class="reference external" href="OCamlLangImpl7.html">Next: Extending the language: mutable variables / SSA
+construction</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl5.html" title="5. Kaleidoscope: Extending the Language: Control Flow"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl7.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl7.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl7.html (added)
+++ www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl7.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1749 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>7. Kaleidoscope: Extending the Language: Mutable Variables — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+ <link rel="next" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits" href="OCamlLangImpl8.html" />
+ <link rel="prev" title="6. Kaleidoscope: Extending the Language: User-defined Operators" href="OCamlLangImpl6.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="kaleidoscope-extending-the-language-mutable-variables">
+<h1>7. Kaleidoscope: Extending the Language: Mutable Variables<a class="headerlink" href="#kaleidoscope-extending-the-language-mutable-variables" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#chapter-7-introduction" id="id2">Chapter 7 Introduction</a></li>
+<li><a class="reference internal" href="#why-is-this-a-hard-problem" id="id3">Why is this a hard problem?</a></li>
+<li><a class="reference internal" href="#memory-in-llvm" id="id4">Memory in LLVM</a></li>
+<li><a class="reference internal" href="#mutable-variables-in-kaleidoscope" id="id5">Mutable Variables in Kaleidoscope</a></li>
+<li><a class="reference internal" href="#adjusting-existing-variables-for-mutation" id="id6">Adjusting Existing Variables for Mutation</a></li>
+<li><a class="reference internal" href="#new-assignment-operator" id="id7">New Assignment Operator</a></li>
+<li><a class="reference internal" href="#user-defined-local-variables" id="id8">User-defined Local Variables</a></li>
+<li><a class="reference internal" href="#id1" id="id9">Full Code Listing</a></li>
+</ul>
+</div>
+<div class="section" id="chapter-7-introduction">
+<h2><a class="toc-backref" href="#id2">7.1. Chapter 7 Introduction</a><a class="headerlink" href="#chapter-7-introduction" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to Chapter 7 of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. In chapters 1 through 6, we’ve built a
+very respectable, albeit simple, <a class="reference external" href="http://en.wikipedia.org/wiki/Functional_programming">functional programming
+language</a>. In our
+journey, we learned some parsing techniques, how to build and represent
+an AST, how to build LLVM IR, and how to optimize the resultant code as
+well as JIT compile it.</p>
+<p>While Kaleidoscope is interesting as a functional language, the fact
+that it is functional makes it “too easy” to generate LLVM IR for it. In
+particular, a functional language makes it very easy to build LLVM IR
+directly in <a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">SSA
+form</a>.
+Since LLVM requires that the input code be in SSA form, this is a very
+nice property and it is often unclear to newcomers how to generate code
+for an imperative language with mutable variables.</p>
+<p>The short (and happy) summary of this chapter is that there is no need
+for your front-end to build SSA form: LLVM provides highly tuned and
+well tested support for this, though the way it works is a bit
+unexpected for some.</p>
+</div>
+<div class="section" id="why-is-this-a-hard-problem">
+<h2><a class="toc-backref" href="#id3">7.2. Why is this a hard problem?</a><a class="headerlink" href="#why-is-this-a-hard-problem" title="Permalink to this headline">¶</a></h2>
+<p>To understand why mutable variables cause complexities in SSA
+construction, consider this extremely simple C example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">G</span><span class="p">,</span> <span class="n">H</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">test</span><span class="p">(</span><span class="kt">_Bool</span> <span class="n">Condition</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">X</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Condition</span><span class="p">)</span>
+ <span class="n">X</span> <span class="o">=</span> <span class="n">G</span><span class="p">;</span>
+ <span class="k">else</span>
+ <span class="n">X</span> <span class="o">=</span> <span class="n">H</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">X</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case, we have the variable “X”, whose value depends on the path
+executed in the program. Because there are two different possible values
+for X before the return instruction, a PHI node is inserted to merge the
+two values. The LLVM IR that we want for this example looks like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@G</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span> <span class="c">; type of @G is i32*</span>
+<span class="vg">@H</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span> <span class="c">; type of @H is i32*</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%Condition</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%Condition</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_false</span>
+
+<span class="nl">cond_true:</span>
+ <span class="nv">%X.0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@G</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_false:</span>
+ <span class="nv">%X.1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@H</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_next:</span>
+ <span class="nv">%X.2</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i32</span> <span class="p">[</span> <span class="nv">%X.1</span><span class="p">,</span> <span class="nv">%cond_false</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%X.0</span><span class="p">,</span> <span class="nv">%cond_true</span> <span class="p">]</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="nv">%X.2</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, the loads from the G and H global variables are
+explicit in the LLVM IR, and they live in the then/else branches of the
+if statement (cond_true/cond_false). In order to merge the incoming
+values, the X.2 phi node in the cond_next block selects the right value
+to use based on where control flow is coming from: if control flow comes
+from the cond_false block, X.2 gets the value of X.1. Alternatively, if
+control flow comes from cond_true, it gets the value of X.0. The intent
+of this chapter is not to explain the details of SSA form. For more
+information, see one of the many <a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">online
+references</a>.</p>
+<p>The question for this article is “who places the phi nodes when lowering
+assignments to mutable variables?”. The issue here is that LLVM
+<em>requires</em> that its IR be in SSA form: there is no “non-ssa” mode for
+it. However, SSA construction requires non-trivial algorithms and data
+structures, so it is inconvenient and wasteful for every front-end to
+have to reproduce this logic.</p>
+</div>
+<div class="section" id="memory-in-llvm">
+<h2><a class="toc-backref" href="#id4">7.3. Memory in LLVM</a><a class="headerlink" href="#memory-in-llvm" title="Permalink to this headline">¶</a></h2>
+<p>The ‘trick’ here is that while LLVM does require all register values to
+be in SSA form, it does not require (or permit) memory objects to be in
+SSA form. In the example above, note that the loads from G and H are
+direct accesses to G and H: they are not renamed or versioned. This
+differs from some other compiler systems, which do try to version memory
+objects. In LLVM, instead of encoding dataflow analysis of memory into
+the LLVM IR, it is handled with <a class="reference external" href="../WritingAnLLVMPass.html">Analysis
+Passes</a> which are computed on demand.</p>
+<p>With this in mind, the high-level idea is that we want to make a stack
+variable (which lives in memory, because it is on the stack) for each
+mutable object in a function. To take advantage of this trick, we need
+to talk about how LLVM represents stack variables.</p>
+<p>In LLVM, all memory accesses are explicit with load/store instructions,
+and it is carefully designed not to have (or need) an “address-of”
+operator. Notice how the type of the @G/@H global variables is actually
+“i32*” even though the variable is defined as “i32”. What this means is
+that @G defines <em>space</em> for an i32 in the global data area, but its
+<em>name</em> actually refers to the address for that space. Stack variables
+work the same way, except that instead of being declared with global
+variable definitions, they are declared with the <a class="reference external" href="../LangRef.html#alloca-instruction">LLVM alloca
+instruction</a>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@example</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span> <span class="c">; type of %X is i32*.</span>
+ <span class="p">...</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="c">; load the stack value %X from the stack.</span>
+ <span class="nv">%tmp2</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="m">1</span> <span class="c">; increment it</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp2</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="c">; store it back</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>This code shows an example of how you can declare and manipulate a stack
+variable in the LLVM IR. Stack memory allocated with the alloca
+instruction is fully general: you can pass the address of the stack slot
+to functions, you can store it in other variables, etc. In our example
+above, we could rewrite the example to use the alloca technique to avoid
+using a PHI node:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@G</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span> <span class="c">; type of @G is i32*</span>
+<span class="vg">@H</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span> <span class="c">; type of @H is i32*</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%Condition</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span> <span class="c">; type of %X is i32*.</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%Condition</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_false</span>
+
+<span class="nl">cond_true:</span>
+ <span class="nv">%X.0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@G</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%X.0</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="c">; Update X</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_false:</span>
+ <span class="nv">%X.1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@H</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%X.1</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="c">; Update X</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_next:</span>
+ <span class="nv">%X.2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="c">; Read X</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="nv">%X.2</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>With this, we have discovered a way to handle arbitrary mutable
+variables without the need to create Phi nodes at all:</p>
+<ol class="arabic simple">
+<li>Each mutable variable becomes a stack allocation.</li>
+<li>Each read of the variable becomes a load from the stack.</li>
+<li>Each update of the variable becomes a store to the stack.</li>
+<li>Taking the address of a variable just uses the stack address
+directly.</li>
+</ol>
+<p>While this solution has solved our immediate problem, it introduced
+another one: we have now apparently introduced a lot of stack traffic
+for very simple and common operations, a major performance problem.
+Fortunately for us, the LLVM optimizer has a highly-tuned optimization
+pass named “mem2reg” that handles this case, promoting allocas like this
+into SSA registers, inserting Phi nodes as appropriate. If you run this
+example through the pass, for example, you’ll get:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>llvm-as < example.ll | opt -mem2reg | llvm-dis
+ at G <span class="o">=</span> weak global i32 0
+ at H <span class="o">=</span> weak global i32 0
+
+define i32 @test<span class="o">(</span>i1 %Condition<span class="o">)</span> <span class="o">{</span>
+entry:
+ br i1 %Condition, label %cond_true, label %cond_false
+
+cond_true:
+ %X.0 <span class="o">=</span> load i32* @G
+ br label %cond_next
+
+cond_false:
+ %X.1 <span class="o">=</span> load i32* @H
+ br label %cond_next
+
+cond_next:
+ %X.01 <span class="o">=</span> phi i32 <span class="o">[</span> %X.1, %cond_false <span class="o">]</span>, <span class="o">[</span> %X.0, %cond_true <span class="o">]</span>
+ ret i32 %X.01
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>The mem2reg pass implements the standard “iterated dominance frontier”
+algorithm for constructing SSA form and has a number of optimizations
+that speed up (very common) degenerate cases. The mem2reg optimization
+pass is the answer to dealing with mutable variables, and we highly
+recommend that you depend on it. Note that mem2reg only works on
+variables in certain circumstances:</p>
+<ol class="arabic simple">
+<li>mem2reg is alloca-driven: it looks for allocas and if it can handle
+them, it promotes them. It does not apply to global variables or heap
+allocations.</li>
+<li>mem2reg only looks for alloca instructions in the entry block of the
+function. Being in the entry block guarantees that the alloca is only
+executed once, which makes analysis simpler.</li>
+<li>mem2reg only promotes allocas whose uses are direct loads and stores.
+If the address of the stack object is passed to a function, or if any
+funny pointer arithmetic is involved, the alloca will not be
+promoted.</li>
+<li>mem2reg only works on allocas of <a class="reference external" href="../LangRef.html#first-class-types">first
+class</a> values (such as pointers,
+scalars and vectors), and only if the array size of the allocation is
+1 (or missing in the .ll file). mem2reg is not capable of promoting
+structs or arrays to registers. Note that the “sroa” pass is
+more powerful and can promote structs, “unions”, and arrays in many
+cases.</li>
+</ol>
+<p>All of these properties are easy to satisfy for most imperative
+languages, and we’ll illustrate it below with Kaleidoscope. The final
+question you may be asking is: should I bother with this nonsense for my
+front-end? Wouldn’t it be better if I just did SSA construction
+directly, avoiding use of the mem2reg optimization pass? In short, we
+strongly recommend that you use this technique for building SSA form,
+unless there is an extremely good reason not to. Using this technique
+is:</p>
+<ul class="simple">
+<li>Proven and well tested: clang uses this technique
+for local mutable variables. As such, the most common clients of LLVM
+are using this to handle a bulk of their variables. You can be sure
+that bugs are found fast and fixed early.</li>
+<li>Extremely Fast: mem2reg has a number of special cases that make it
+fast in common cases as well as fully general. For example, it has
+fast-paths for variables that are only used in a single block,
+variables that only have one assignment point, good heuristics to
+avoid insertion of unneeded phi nodes, etc.</li>
+<li>Needed for debug info generation: <a class="reference external" href="../SourceLevelDebugging.html">Debug information in
+LLVM</a> relies on having the address of
+the variable exposed so that debug info can be attached to it. This
+technique dovetails very naturally with this style of debug info.</li>
+</ul>
+<p>If nothing else, this makes it much easier to get your front-end up and
+running, and is very simple to implement. Lets extend Kaleidoscope with
+mutable variables now!</p>
+</div>
+<div class="section" id="mutable-variables-in-kaleidoscope">
+<h2><a class="toc-backref" href="#id5">7.4. Mutable Variables in Kaleidoscope</a><a class="headerlink" href="#mutable-variables-in-kaleidoscope" title="Permalink to this headline">¶</a></h2>
+<p>Now that we know the sort of problem we want to tackle, lets see what
+this looks like in the context of our little Kaleidoscope language.
+We’re going to add two features:</p>
+<ol class="arabic simple">
+<li>The ability to mutate variables with the ‘=’ operator.</li>
+<li>The ability to define new variables.</li>
+</ol>
+<p>While the first item is really what this is about, we only have
+variables for incoming arguments as well as for induction variables, and
+redefining those only goes so far :). Also, the ability to define new
+variables is a useful thing regardless of whether you will be mutating
+them. Here’s a motivating example that shows how we could use these:</p>
+<div class="highlight-python"><pre># Define ':' for sequencing: as a low-precedence operator that ignores operands
+# and just returns the RHS.
+def binary : 1 (x y) y;
+
+# Recursive fib, we could do this before.
+def fib(x)
+ if (x < 3) then
+ 1
+ else
+ fib(x-1)+fib(x-2);
+
+# Iterative fib.
+def fibi(x)
+ var a = 1, b = 1, c in
+ (for i = 3, i < x in
+ c = a + b :
+ a = b :
+ b = c) :
+ b;
+
+# Call it.
+fibi(10);</pre>
+</div>
+<p>In order to mutate variables, we have to change our existing variables
+to use the “alloca trick”. Once we have that, we’ll add our new
+operator, then extend Kaleidoscope to support new variable definitions.</p>
+</div>
+<div class="section" id="adjusting-existing-variables-for-mutation">
+<h2><a class="toc-backref" href="#id6">7.5. Adjusting Existing Variables for Mutation</a><a class="headerlink" href="#adjusting-existing-variables-for-mutation" title="Permalink to this headline">¶</a></h2>
+<p>The symbol table in Kaleidoscope is managed at code generation time by
+the ‘<tt class="docutils literal"><span class="pre">named_values</span></tt>‘ map. This map currently keeps track of the LLVM
+“Value*” that holds the double value for the named variable. In order
+to support mutation, we need to change this slightly, so that it
+<tt class="docutils literal"><span class="pre">named_values</span></tt> holds the <em>memory location</em> of the variable in
+question. Note that this change is a refactoring: it changes the
+structure of the code, but does not (by itself) change the behavior of
+the compiler. All of these changes are isolated in the Kaleidoscope code
+generator.</p>
+<p>At this point in Kaleidoscope’s development, it only supports variables
+for two things: incoming arguments to functions and the induction
+variable of ‘for’ loops. For consistency, we’ll allow mutation of these
+variables in addition to other user-defined variables. This means that
+these will both need memory locations.</p>
+<p>To start our transformation of Kaleidoscope, we’ll change the
+<tt class="docutils literal"><span class="pre">named_values</span></tt> map so that it maps to AllocaInst* instead of Value*.
+Once we do this, the C++ compiler will tell us what parts of the code we
+need to update:</p>
+<p><strong>Note:</strong> the ocaml bindings currently model both <tt class="docutils literal"><span class="pre">Value*</span></tt>‘s and
+<tt class="docutils literal"><span class="pre">AllocInst*</span></tt>‘s as <tt class="docutils literal"><span class="pre">Llvm.llvalue</span></tt>‘s, but this may change in the future
+to be more type safe.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+</pre></div>
+</div>
+<p>Also, since we will need to create these alloca’s, we’ll use a helper
+function that ensures that the allocas are created in the entry block of
+the function:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Create an alloca instruction in the entry block of the function. This</span>
+<span class="c"> * is used for mutable variables etc. *)</span>
+<span class="k">let</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder_at</span> <span class="o">(</span><span class="n">instr_begin</span> <span class="o">(</span><span class="n">entry_block</span> <span class="n">the_function</span><span class="o">))</span> <span class="k">in</span>
+ <span class="n">build_alloca</span> <span class="n">double_type</span> <span class="n">var_name</span> <span class="n">builder</span>
+</pre></div>
+</div>
+<p>This funny looking code creates an <tt class="docutils literal"><span class="pre">Llvm.llbuilder</span></tt> object that is
+pointing at the first instruction of the entry block. It then creates an
+alloca with the expected name and returns it. Because all values in
+Kaleidoscope are doubles, there is no need to pass in a type to use.</p>
+<p>With this in place, the first functionality change we want to make is to
+variable references. In our new scheme, variables live on the stack, so
+code generating a reference to them actually needs to produce a load
+from the stack slot:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">v</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="c">(* Load the value. *)</span>
+ <span class="n">build_load</span> <span class="n">v</span> <span class="n">name</span> <span class="n">builder</span>
+</pre></div>
+</div>
+<p>As you can see, this is pretty straightforward. Now we need to update
+the things that define the variables to set up the alloca. We’ll start
+with <tt class="docutils literal"><span class="pre">codegen_expr</span> <span class="pre">Ast.For</span> <span class="pre">...</span></tt> (see the <a class="reference external" href="#id1">full code listing</a>
+for the unabridged code):</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Create an alloca for the variable in the entry block. *)</span>
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+ <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+ <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+ <span class="c">(* Store the value into the alloca. *)</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">start_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="o">...</span>
+
+ <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c"> * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c"> * now. *)</span>
+ <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+ <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+
+ <span class="o">...</span>
+
+ <span class="c">(* Compute the end condition. *)</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+ <span class="c">(* Reload, increment, and restore the alloca. This handles the case where</span>
+<span class="c"> * the body of the loop mutates the variable. *)</span>
+ <span class="k">let</span> <span class="n">cur_var</span> <span class="o">=</span> <span class="n">build_load</span> <span class="n">alloca</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">cur_var</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">next_var</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>This code is virtually identical to the code <a class="reference external" href="OCamlLangImpl5.html#code-generation-for-the-for-loop">before we allowed mutable
+variables</a>. The big difference is that
+we no longer have to construct a PHI node, and we use load/store to
+access the variable as needed.</p>
+<p>To support mutable argument variables, we need to also make allocas for
+them. The code for this is also pretty simple:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Create an alloca for each argument and register the argument in the symbol</span>
+<span class="c"> * table so that references to it will succeed. *)</span>
+<span class="k">let</span> <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span> <span class="n">args</span>
+ <span class="k">in</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">ai</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">var_name</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+ <span class="c">(* Create an alloca for this variable. *)</span>
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+ <span class="c">(* Store the initial value into the alloca. *)</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">ai</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Add arguments to variable symbol table. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+ <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">the_function</span><span class="o">)</span>
+</pre></div>
+</div>
+<p>For each argument, we make an alloca, store the input value to the
+function into the alloca, and register the alloca as the memory location
+for the argument. This method gets invoked by <tt class="docutils literal"><span class="pre">Codegen.codegen_func</span></tt>
+right after it sets up the entry block for the function.</p>
+<p>The final missing piece is adding the mem2reg pass, which allows us to
+get good codegen once again:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+ <span class="c">(* Set up the optimizer pipeline. Start with registering info about how the</span>
+<span class="c"> * target lays out data structures. *)</span>
+ <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Promote allocas to registers. *)</span>
+ <span class="n">add_memory_to_register_promotion</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+ <span class="n">add_instruction_combining</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* reassociate expressions. *)</span>
+ <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>It is interesting to see what the code looks like before and after the
+mem2reg optimization runs. For example, this is the before/after code
+for our recursive fib function. Before the optimization:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%x1</span> <span class="p">=</span> <span class="k">alloca</span> <span class="kt">double</span>
+ <span class="k">store</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+ <span class="nv">%x2</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+ <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x2</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+ <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+ <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span>
+
+<span class="nl">then:</span> <span class="c">; preds = %entry</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span> <span class="c">; preds = %entry</span>
+ <span class="nv">%x3</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+ <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x3</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+ <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+ <span class="nv">%x4</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+ <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x4</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+ <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+ <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">ifcont:</span> <span class="c">; preds = %else, %then</span>
+ <span class="nv">%iftmp</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="m">1.000000e+00</span><span class="p">,</span> <span class="nv">%then</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%addtmp</span><span class="p">,</span> <span class="nv">%else</span> <span class="p">]</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%iftmp</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here there is only one variable (x, the input argument) but you can
+still see the extremely simple-minded code generation strategy we are
+using. In the entry block, an alloca is created, and the initial input
+value is stored into it. Each reference to the variable does a reload
+from the stack. Also, note that we didn’t modify the if/then/else
+expression, so it still inserts a PHI node. While we could make an
+alloca for it, it is actually easier to create a PHI node for it, so we
+still just make the PHI.</p>
+<p>Here is the code after the mem2reg pass runs:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+ <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+ <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span>
+
+<span class="nl">then:</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span>
+ <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+ <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+ <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+ <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+ <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">ifcont:</span> <span class="c">; preds = %else, %then</span>
+ <span class="nv">%iftmp</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="m">1.000000e+00</span><span class="p">,</span> <span class="nv">%then</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%addtmp</span><span class="p">,</span> <span class="nv">%else</span> <span class="p">]</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%iftmp</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is a trivial case for mem2reg, since there are no redefinitions of
+the variable. The point of showing this is to calm your tension about
+inserting such blatent inefficiencies :).</p>
+<p>After the rest of the optimizers run, we get:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+ <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+ <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ueq</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span>
+ <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+ <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+ <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+ <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+ <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%addtmp</span>
+
+<span class="nl">ifcont:</span>
+ <span class="k">ret</span> <span class="kt">double</span> <span class="m">1.000000e+00</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here we see that the simplifycfg pass decided to clone the return
+instruction into the end of the ‘else’ block. This allowed it to
+eliminate some branches and the PHI node.</p>
+<p>Now that all symbol table references are updated to use stack variables,
+we’ll add the assignment operator.</p>
+</div>
+<div class="section" id="new-assignment-operator">
+<h2><a class="toc-backref" href="#id7">7.6. New Assignment Operator</a><a class="headerlink" href="#new-assignment-operator" title="Permalink to this headline">¶</a></h2>
+<p>With our current framework, adding a new assignment operator is really
+simple. We will parse it just like any other binary operator, but handle
+it internally (instead of allowing the user to define it). The first
+step is to set a precedence:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+ <span class="c">(* Install standard binary operators.</span>
+<span class="c"> * 1 is the lowest precedence. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'='</span> <span class="mi">2</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>Now that the parser knows the precedence of the binary operator, it
+takes care of all the parsing and AST generation. We just need to
+implement codegen for the assignment operator. This looks like:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'='</span> <span class="o">-></span>
+ <span class="c">(* Special case '=' because we don't want to emit the LHS as an</span>
+<span class="c"> * expression. *)</span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lhs</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span> <span class="n">name</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"destination of '=' must be a variable"</span><span class="o">)</span>
+ <span class="k">in</span>
+</pre></div>
+</div>
+<p>Unlike the rest of the binary operators, our assignment operator doesn’t
+follow the “emit LHS, emit RHS, do computation” model. As such, it is
+handled as a special case before the other binary operators are handled.
+The other strange thing is that it requires the LHS to be a variable. It
+is invalid to have “(x+1) = expr” - only things like “x = expr” are
+allowed.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre> <span class="c">(* Codegen the rhs. *)</span>
+ <span class="k">let</span> <span class="n">val_</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+
+ <span class="c">(* Lookup the name. *)</span>
+ <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">val_</span> <span class="n">variable</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="n">val_</span>
+<span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>Once we have the variable, codegen’ing the assignment is
+straightforward: we emit the RHS of the assignment, create a store, and
+return the computed value. Returning a value allows for chained
+assignments like “X = (Y = Z)”.</p>
+<p>Now that we have an assignment operator, we can mutate loop variables
+and arguments. For example, we can now run code like this:</p>
+<div class="highlight-python"><pre># Function to print a double.
+extern printd(x);
+
+# Define ':' for sequencing: as a low-precedence operator that ignores operands
+# and just returns the RHS.
+def binary : 1 (x y) y;
+
+def test(x)
+ printd(x) :
+ x = 4 :
+ printd(x);
+
+test(123);</pre>
+</div>
+<p>When run, this example prints “123” and then “4”, showing that we did
+actually mutate the value! Okay, we have now officially implemented our
+goal: getting this to work requires SSA construction in the general
+case. However, to be really useful, we want the ability to define our
+own local variables, lets add this next!</p>
+</div>
+<div class="section" id="user-defined-local-variables">
+<h2><a class="toc-backref" href="#id8">7.7. User-defined Local Variables</a><a class="headerlink" href="#user-defined-local-variables" title="Permalink to this headline">¶</a></h2>
+<p>Adding var/in is just like any other other extensions we made to
+Kaleidoscope: we extend the lexer, the parser, the AST and the code
+generator. The first step for adding our new ‘var/in’ construct is to
+extend the lexer. As before, this is pretty trivial, the code looks like
+this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* var definition *)</span>
+ <span class="o">|</span> <span class="nn">Var</span>
+
+<span class="p">...</span>
+
+<span class="n">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"var"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>The next step is to define the AST node that we will construct. For
+var/in, it looks like this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="o">...</span>
+ <span class="c">(* variant for var/in. *)</span>
+ <span class="o">|</span> <span class="nc">Var</span> <span class="k">of</span> <span class="o">(</span><span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span><span class="o">)</span> <span class="kt">array</span> <span class="o">*</span> <span class="n">expr</span>
+ <span class="o">...</span>
+</pre></div>
+</div>
+<p>var/in allows a list of names to be defined all at once, and each name
+can optionally have an initializer value. As such, we capture this
+information in the VarNames vector. Also, var/in has a body, this body
+is allowed to access the variables defined by the var/in.</p>
+<p>With this in place, we can define the parser pieces. The first thing we
+do is add it as a primary expression:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* primary</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= numberexpr</span>
+<span class="c"> * ::= parenexpr</span>
+<span class="c"> * ::= ifexpr</span>
+<span class="c"> * ::= forexpr</span>
+<span class="c"> * ::= varexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">...</span>
+ <span class="c">(* varexpr</span>
+<span class="c"> * ::= 'var' identifier ('=' expression?</span>
+<span class="c"> * (',' identifier ('=' expression)?)* 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span>
+ <span class="c">(* At least one variable name is required. *)</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after var"</span><span class="o">;</span>
+ <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+ <span class="n">var_names</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">[(</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)];</span>
+ <span class="c">(* At this point, we have to have 'in'. *)</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span> <span class="o">??</span> <span class="s2">"expected 'in' keyword after 'var'"</span><span class="o">;</span>
+ <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">var_names</span><span class="o">),</span> <span class="n">body</span><span class="o">)</span>
+
+<span class="o">...</span>
+
+<span class="ow">and</span> <span class="n">parse_var_init</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* read in the optional initializer. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+
+<span class="ow">and</span> <span class="n">parse_var_names</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier list after var"</span><span class="o">;</span>
+ <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+ <span class="n">e</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">((</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+</pre></div>
+</div>
+<p>Now that we can parse and represent the code, we need to support
+emission of LLVM IR for it. This code starts out with:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">...</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="n">var_names</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+ <span class="k">let</span> <span class="n">old_bindings</span> <span class="o">=</span> <span class="n">ref</span> <span class="bp">[]</span> <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Register all variables and emit their initializer. *)</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">-></span>
+</pre></div>
+</div>
+<p>Basically it loops over all the variables, installing them one at a
+time. For each variable we put into the symbol table, we remember the
+previous value that we replace in OldBindings.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre> <span class="c">(* Emit the initializer before adding the variable to scope, this</span>
+<span class="c"> * prevents the initializer from referencing the variable itself, and</span>
+<span class="c"> * permits stuff like this:</span>
+<span class="c"> * var a = 1 in</span>
+<span class="c"> * var a = a in ... # refers to outer 'a'. *)</span>
+ <span class="k">let</span> <span class="n">init_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">init</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">init</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">init</span>
+ <span class="c">(* If not specified, use 0.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span>
+ <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">init_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Remember the old variable binding so that we can restore the binding</span>
+<span class="c"> * when we unrecurse. *)</span>
+
+ <span class="k">begin</span>
+ <span class="k">try</span>
+ <span class="k">let</span> <span class="n">old_value</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="k">in</span>
+ <span class="n">old_bindings</span> <span class="o">:=</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">::</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+ <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* Remember this binding. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+<span class="o">)</span> <span class="n">var_names</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>There are more comments here than code. The basic idea is that we emit
+the initializer, create the alloca, then update the symbol table to
+point to it. Once all the variables are installed in the symbol table,
+we evaluate the body of the var/in expression:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Codegen the body, now that all vars are in scope. *)</span>
+<span class="k">let</span> <span class="n">body_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Finally, before returning, we restore the previous variable bindings:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Pop all our variables from scope. *)</span>
+<span class="nn">List</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_value</span>
+<span class="o">)</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+
+<span class="c">(* Return the body computation. *)</span>
+<span class="n">body_val</span>
+</pre></div>
+</div>
+<p>The end result of all of this is that we get properly scoped variable
+definitions, and we even (trivially) allow mutation of them :).</p>
+<p>With this, we completed what we set out to do. Our nice iterative fib
+example from the intro compiles and runs just fine. The mem2reg pass
+optimizes all of our stack variables into SSA registers, inserting PHI
+nodes where needed, and our front-end remains simple: no “iterated
+dominance frontier” computation anywhere in sight.</p>
+</div>
+<div class="section" id="id1">
+<h2><a class="toc-backref" href="#id9">7.8. Full Code Listing</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
+<p>Here is the complete code listing for our running example, enhanced with
+mutable variables and var/in support. To build this example, use:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Compile</span>
+ocamlbuild toy.byte
+<span class="c"># Run</span>
+./toy.byte
+</pre></div>
+</div>
+<p>Here is the code:</p>
+<dl class="docutils">
+<dt>_tags:</dt>
+<dd><div class="first last highlight-python"><pre><{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
+<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
+<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
+<*.{byte,native}>: use_llvm_scalar_opts, use_bindings</pre>
+</div>
+</dd>
+<dt>myocamlbuild.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="k">open</span> <span class="nc">Ocamlbuild_plugin</span><span class="o">;;</span>
+
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_analysis"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_executionengine"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_target"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_scalar_opts"</span><span class="o">;;</span>
+
+<span class="n">flag</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"g++"</span><span class="o">]</span> <span class="o">(</span><span class="nc">S</span><span class="o">[</span><span class="nc">A</span><span class="s2">"-cc"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"g++"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-cclib"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-rdynamic"</span><span class="o">]);;</span>
+<span class="n">dep</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"use_bindings"</span><span class="o">]</span> <span class="o">[</span><span class="s2">"bindings.o"</span><span class="o">];;</span>
+</pre></div>
+</div>
+</dd>
+<dt>token.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer Tokens</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of</span>
+<span class="c"> * these others for known things. *)</span>
+<span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+ <span class="c">(* commands *)</span>
+ <span class="o">|</span> <span class="nc">Def</span> <span class="o">|</span> <span class="nc">Extern</span>
+
+ <span class="c">(* primary *)</span>
+ <span class="o">|</span> <span class="nc">Ident</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* unknown *)</span>
+ <span class="o">|</span> <span class="nc">Kwd</span> <span class="k">of</span> <span class="kt">char</span>
+
+ <span class="c">(* control *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nc">In</span>
+
+ <span class="c">(* operators *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="o">|</span> <span class="nc">Unary</span>
+
+ <span class="c">(* var definition *)</span>
+ <span class="o">|</span> <span class="nc">Var</span>
+</pre></div>
+</div>
+</dd>
+<dt>lexer.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">lex</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Skip any whitespace. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">' '</span> <span class="o">|</span> <span class="sc">'\n'</span> <span class="o">|</span> <span class="sc">'\r'</span> <span class="o">|</span> <span class="sc">'\t'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">lex</span> <span class="n">stream</span>
+
+ <span class="c">(* identifier: [a-zA-Z][a-zA-Z0-9] *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* number: [0-9.]+ *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+ <span class="c">(* Comment until end of line. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'#'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="n">lex_comment</span> <span class="n">stream</span>
+
+ <span class="c">(* Otherwise, just return the character as its ascii value. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">;</span> <span class="n">lex</span> <span class="n">stream</span> <span class="o">>]</span>
+
+ <span class="c">(* end of stream. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_number</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="o">|</span> <span class="sc">'.'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="o">(</span><span class="n">float_of_string</span> <span class="o">(</span><span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span><span class="o">));</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="o">|</span> <span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+ <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="s2">"var"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+ <span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_comment</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'\n'</span><span class="o">);</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">lex_comment</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</dd>
+<dt>ast.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Abstract Syntax Tree (aka Parse Tree)</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* expr - Base type for all expression nodes. *)</span>
+<span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+ <span class="c">(* variant for numeric literals like "1.0". *)</span>
+ <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+ <span class="c">(* variant for referencing a variable, like "a". *)</span>
+ <span class="o">|</span> <span class="nc">Variable</span> <span class="k">of</span> <span class="kt">string</span>
+
+ <span class="c">(* variant for a unary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Unary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for a binary operator. *)</span>
+ <span class="o">|</span> <span class="nc">Binary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for function calls. *)</span>
+ <span class="o">|</span> <span class="nc">Call</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="kt">array</span>
+
+ <span class="c">(* variant for if/then/else. *)</span>
+ <span class="o">|</span> <span class="nc">If</span> <span class="k">of</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for for/in. *)</span>
+ <span class="o">|</span> <span class="nc">For</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span> <span class="o">*</span> <span class="n">expr</span>
+
+ <span class="c">(* variant for var/in. *)</span>
+ <span class="o">|</span> <span class="nc">Var</span> <span class="k">of</span> <span class="o">(</span><span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span><span class="o">)</span> <span class="kt">array</span> <span class="o">*</span> <span class="n">expr</span>
+
+<span class="c">(* proto - This type represents the "prototype" for a function, which captures</span>
+<span class="c"> * its name, and its argument names (thus implicitly the number of arguments the</span>
+<span class="c"> * function takes). *)</span>
+<span class="k">type</span> <span class="n">proto</span> <span class="o">=</span>
+ <span class="o">|</span> <span class="nc">Prototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span>
+ <span class="o">|</span> <span class="nc">BinOpPrototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span> <span class="o">*</span> <span class="kt">int</span>
+
+<span class="c">(* func - This type represents a function definition itself. *)</span>
+<span class="k">type</span> <span class="n">func</span> <span class="o">=</span> <span class="nc">Function</span> <span class="k">of</span> <span class="n">proto</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+</dd>
+<dt>parser.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===---------------------------------------------------------------------===</span>
+<span class="c"> * Parser</span>
+<span class="c"> *===---------------------------------------------------------------------===*)</span>
+
+<span class="c">(* binop_precedence - This holds the precedence for each binary operator that is</span>
+<span class="c"> * defined *)</span>
+<span class="k">let</span> <span class="n">binop_precedence</span><span class="o">:(</span><span class="kt">char</span><span class="o">,</span> <span class="kt">int</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+
+<span class="c">(* precedence - Get the precedence of the pending binary operator token. *)</span>
+<span class="k">let</span> <span class="n">precedence</span> <span class="n">c</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="o">-</span><span class="mi">1</span>
+
+<span class="c">(* primary</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= numberexpr</span>
+<span class="c"> * ::= parenexpr</span>
+<span class="c"> * ::= ifexpr</span>
+<span class="c"> * ::= forexpr</span>
+<span class="c"> * ::= varexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* numberexpr ::= number *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span>
+
+ <span class="c">(* parenexpr ::= '(' expression ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+
+ <span class="c">(* identifierexpr</span>
+<span class="c"> * ::= identifier</span>
+<span class="c"> * ::= identifier '(' argumentexpr ')' *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_ident</span> <span class="n">id</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* Call. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span><span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+
+ <span class="c">(* Simple variable ref. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">id</span>
+ <span class="k">in</span>
+ <span class="n">parse_ident</span> <span class="n">id</span> <span class="n">stream</span>
+
+ <span class="c">(* ifexpr ::= 'if' expr 'then' expr 'else' expr *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">c</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span> <span class="o">??</span> <span class="s2">"expected 'then'"</span><span class="o">;</span> <span class="n">t</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span> <span class="o">??</span> <span class="s2">"expected 'else'"</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">t</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+ <span class="c">(* forexpr</span>
+<span class="c"> ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after for"</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span> <span class="o">??</span> <span class="s2">"expected '=' after for"</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span>
+ <span class="n">start</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span> <span class="o">??</span> <span class="s2">"expected ',' after for"</span><span class="o">;</span>
+ <span class="n">end_</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+ <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">step</span> <span class="o">=</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">step</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">step</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="k">in</span>
+ <span class="k">begin</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected 'in' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected '=' after for"</span><span class="o">)</span>
+ <span class="k">end</span> <span class="n">stream</span>
+
+ <span class="c">(* varexpr</span>
+<span class="c"> * ::= 'var' identifier ('=' expression?</span>
+<span class="c"> * (',' identifier ('=' expression)?)* 'in' expression *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span>
+ <span class="c">(* At least one variable name is required. *)</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after var"</span><span class="o">;</span>
+ <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+ <span class="n">var_names</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">[(</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)];</span>
+ <span class="c">(* At this point, we have to have 'in'. *)</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span> <span class="o">??</span> <span class="s2">"expected 'in' keyword after 'var'"</span><span class="o">;</span>
+ <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">var_names</span><span class="o">),</span> <span class="n">body</span><span class="o">)</span>
+
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"unknown token when expecting an expression."</span><span class="o">)</span>
+
+<span class="c">(* unary</span>
+<span class="c"> * ::= primary</span>
+<span class="c"> * ::= '!' unary *)</span>
+<span class="ow">and</span> <span class="n">parse_unary</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* If this is a unary operator, read it. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="k">when</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">'('</span> <span class="o">&&</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">')'</span><span class="o">;</span> <span class="n">operand</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span>
+
+ <span class="c">(* If the current token is not an operator, it must be a primary expr. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_primary</span> <span class="n">stream</span>
+
+<span class="c">(* binoprhs</span>
+<span class="c"> * ::= ('+' primary)* *)</span>
+<span class="ow">and</span> <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="c">(* If this is a binop, find its precedence. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">)</span> <span class="k">when</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">mem</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">token_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c</span> <span class="k">in</span>
+
+ <span class="c">(* If this is a binop that binds at least as tightly as the current binop,</span>
+<span class="c"> * consume it, otherwise we are done. *)</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">expr_prec</span> <span class="k">then</span> <span class="n">lhs</span> <span class="k">else</span> <span class="k">begin</span>
+ <span class="c">(* Eat the binop. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Parse the primary expression after the binary operator. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span> <span class="n">parse_unary</span> <span class="n">stream</span> <span class="k">in</span>
+
+ <span class="c">(* Okay, we know this is a binop. *)</span>
+ <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c2</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* If BinOp binds less tightly with rhs than the operator after</span>
+<span class="c"> * rhs, let the pending operator take rhs as its lhs. *)</span>
+ <span class="k">let</span> <span class="n">next_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c2</span> <span class="k">in</span>
+ <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">next_prec</span>
+ <span class="k">then</span> <span class="n">parse_bin_rhs</span> <span class="o">(</span><span class="n">token_prec</span> <span class="o">+</span> <span class="mi">1</span><span class="o">)</span> <span class="n">rhs</span> <span class="n">stream</span>
+ <span class="k">else</span> <span class="n">rhs</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">rhs</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Merge lhs/rhs. *)</span>
+ <span class="k">let</span> <span class="n">lhs</span> <span class="o">=</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">lhs</span>
+
+<span class="ow">and</span> <span class="n">parse_var_init</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="c">(* read in the optional initializer. *)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+
+<span class="ow">and</span> <span class="n">parse_var_names</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier list after var"</span><span class="o">;</span>
+ <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+ <span class="n">e</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">((</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+
+<span class="c">(* expression</span>
+<span class="c"> * ::= primary binoprhs *)</span>
+<span class="ow">and</span> <span class="n">parse_expr</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">lhs</span><span class="o">=</span><span class="n">parse_unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_bin_rhs</span> <span class="mi">0</span> <span class="n">lhs</span> <span class="n">stream</span>
+
+<span class="c">(* prototype</span>
+<span class="c"> * ::= id '(' id* ')'</span>
+<span class="c"> * ::= binary LETTER number? (id, id)</span>
+<span class="c"> * ::= unary LETTER number? (id) *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_operator</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"unary"</span><span class="o">,</span> <span class="mi">1</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"binary"</span><span class="o">,</span> <span class="mi">2</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">parse_binary_precedence</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">int_of_float</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="mi">30</span>
+ <span class="k">in</span>
+ <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* success. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">(</span><span class="n">prefix</span><span class="o">,</span> <span class="n">kind</span><span class="o">)=</span><span class="n">parse_operator</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="o">??</span> <span class="s2">"expected an operator"</span><span class="o">;</span>
+ <span class="c">(* Read the precedence if present. *)</span>
+ <span class="n">binary_precedence</span><span class="o">=</span><span class="n">parse_binary_precedence</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+ <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+ <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span> <span class="n">prefix</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Verify right number of arguments for operator. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="o">!=</span> <span class="n">kind</span>
+ <span class="k">then</span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"invalid number of operands for operator"</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="k">if</span> <span class="n">kind</span> <span class="o">==</span> <span class="mi">1</span> <span class="k">then</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span>
+ <span class="k">else</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">binary_precedence</span><span class="o">)</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+
+<span class="c">(* definition ::= 'def' prototype expression *)</span>
+<span class="k">let</span> <span class="n">parse_definition</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">p</span><span class="o">=</span><span class="n">parse_prototype</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">p</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* toplevelexpr ::= expression *)</span>
+<span class="k">let</span> <span class="n">parse_toplevel</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+ <span class="c">(* Make an anonymous proto. *)</span>
+ <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="s2">""</span><span class="o">,</span> <span class="o">[||]),</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* external ::= 'extern' prototype *)</span>
+<span class="k">let</span> <span class="n">parse_extern</span> <span class="o">=</span> <span class="n">parser</span>
+ <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_prototype</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>codegen.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Code Generation</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+
+<span class="k">exception</span> <span class="nc">Error</span> <span class="k">of</span> <span class="kt">string</span>
+
+<span class="k">let</span> <span class="n">context</span> <span class="o">=</span> <span class="n">global_context</span> <span class="bp">()</span>
+<span class="k">let</span> <span class="n">the_module</span> <span class="o">=</span> <span class="n">create_module</span> <span class="n">context</span> <span class="s2">"my cool jit"</span>
+<span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span> <span class="n">context</span>
+<span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+<span class="k">let</span> <span class="n">double_type</span> <span class="o">=</span> <span class="n">double_type</span> <span class="n">context</span>
+
+<span class="c">(* Create an alloca instruction in the entry block of the function. This</span>
+<span class="c"> * is used for mutable variables etc. *)</span>
+<span class="k">let</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder_at</span> <span class="n">context</span> <span class="o">(</span><span class="n">instr_begin</span> <span class="o">(</span><span class="n">entry_block</span> <span class="n">the_function</span><span class="o">))</span> <span class="k">in</span>
+ <span class="n">build_alloca</span> <span class="n">double_type</span> <span class="n">var_name</span> <span class="n">builder</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="n">n</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">v</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="c">(* Load the value. *)</span>
+ <span class="n">build_load</span> <span class="n">v</span> <span class="n">name</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">operand</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">operand</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"unary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown unary operator"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">operand</span><span class="o">|]</span> <span class="s2">"unop"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'='</span> <span class="o">-></span>
+ <span class="c">(* Special case '=' because we don't want to emit the LHS as an</span>
+<span class="c"> * expression. *)</span>
+ <span class="k">let</span> <span class="n">name</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lhs</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span> <span class="n">name</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"destination of '=' must be a variable"</span><span class="o">)</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Codegen the rhs. *)</span>
+ <span class="k">let</span> <span class="n">val_</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+
+ <span class="c">(* Lookup the name. *)</span>
+ <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">val_</span> <span class="n">variable</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="n">val_</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">lhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">lhs</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">rhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+ <span class="k">begin</span>
+ <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="sc">'+'</span> <span class="o">-></span> <span class="n">build_add</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"addtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'-'</span> <span class="o">-></span> <span class="n">build_sub</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"subtmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'*'</span> <span class="o">-></span> <span class="n">build_mul</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"multmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="sc">'<'</span> <span class="o">-></span>
+ <span class="c">(* Convert bool 0/1 to double 0.0 or 1.0 *)</span>
+ <span class="k">let</span> <span class="n">i</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">Ult</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"cmptmp"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">build_uitofp</span> <span class="n">i</span> <span class="n">double_type</span> <span class="s2">"booltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* If it wasn't a builtin binary operator, it must be a user defined</span>
+<span class="c"> * one. Emit a call to it. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"binary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"binary operator not found!"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">lhs_val</span><span class="o">;</span> <span class="n">rhs_val</span><span class="o">|]</span> <span class="s2">"binop"</span> <span class="n">builder</span>
+ <span class="k">end</span>
+ <span class="k">end</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">callee</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Look up the name in the module table. *)</span>
+ <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown function referenced"</span><span class="o">)</span>
+ <span class="k">in</span>
+ <span class="k">let</span> <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="n">callee</span> <span class="k">in</span>
+
+ <span class="c">(* If argument mismatch error. *)</span>
+ <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">params</span> <span class="o">==</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="k">then</span> <span class="bp">()</span> <span class="k">else</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"incorrect # arguments passed"</span><span class="o">);</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">map</span> <span class="n">codegen_expr</span> <span class="n">args</span> <span class="k">in</span>
+ <span class="n">build_call</span> <span class="n">callee</span> <span class="n">args</span> <span class="s2">"calltmp"</span> <span class="n">builder</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">cond</span><span class="o">,</span> <span class="n">then_</span><span class="o">,</span> <span class="n">else_</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">cond</span> <span class="k">in</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0 *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">cond_val</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">cond</span> <span class="n">zero</span> <span class="s2">"ifcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Grab the first block so that we might later add the conditional branch</span>
+<span class="c"> * to it at the end of the function. *)</span>
+ <span class="k">let</span> <span class="n">start_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">start_bb</span> <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">then_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"then"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'then' value. *)</span>
+ <span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">then_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">then_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'then' can change the current block, update then_bb for the</span>
+<span class="c"> * phi. We create a new name because one is used for the phi node, and the</span>
+<span class="c"> * other is used for the conditional branch. *)</span>
+ <span class="k">let</span> <span class="n">new_then_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit 'else' value. *)</span>
+ <span class="k">let</span> <span class="n">else_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"else"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">else_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">else_</span> <span class="k">in</span>
+
+ <span class="c">(* Codegen of 'else' can change the current block, update else_bb for the</span>
+<span class="c"> * phi. *)</span>
+ <span class="k">let</span> <span class="n">new_else_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Emit merge block. *)</span>
+ <span class="k">let</span> <span class="n">merge_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"ifcont"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">incoming</span> <span class="o">=</span> <span class="o">[(</span><span class="n">then_val</span><span class="o">,</span> <span class="n">new_then_bb</span><span class="o">);</span> <span class="o">(</span><span class="n">else_val</span><span class="o">,</span> <span class="n">new_else_bb</span><span class="o">)]</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">phi</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="n">incoming</span> <span class="s2">"iftmp"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Return to the start block to add the conditional branch. *)</span>
+ <span class="n">position_at_end</span> <span class="n">start_bb</span> <span class="n">builder</span><span class="o">;</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">cond_val</span> <span class="n">then_bb</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Set a unconditional branch at the end of the 'then' block and the</span>
+<span class="c"> * 'else' block to the 'merge' block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">new_then_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+ <span class="n">position_at_end</span> <span class="n">new_else_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Finally, set the builder to the end of the merge block. *)</span>
+ <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="n">phi</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Output this as:</span>
+<span class="c"> * var = alloca double</span>
+<span class="c"> * ...</span>
+<span class="c"> * start = startexpr</span>
+<span class="c"> * store start -> var</span>
+<span class="c"> * goto loop</span>
+<span class="c"> * loop:</span>
+<span class="c"> * ...</span>
+<span class="c"> * bodyexpr</span>
+<span class="c"> * ...</span>
+<span class="c"> * loopend:</span>
+<span class="c"> * step = stepexpr</span>
+<span class="c"> * endcond = endexpr</span>
+<span class="c"> *</span>
+<span class="c"> * curvar = load var</span>
+<span class="c"> * nextvar = curvar + step</span>
+<span class="c"> * store nextvar -> var</span>
+<span class="c"> * br endcond, loop, endloop</span>
+<span class="c"> * outloop: *)</span>
+
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Create an alloca for the variable in the entry block. *)</span>
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+ <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+ <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+ <span class="c">(* Store the value into the alloca. *)</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">start_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Make the new basic block for the loop header, inserting after current</span>
+<span class="c"> * block. *)</span>
+ <span class="k">let</span> <span class="n">loop_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"loop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert an explicit fall through from the current block to the</span>
+<span class="c"> * loop_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Start insertion in loop_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c"> * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c"> * now. *)</span>
+ <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+ <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+ <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+
+ <span class="c">(* Emit the body of the loop. This, like any other expr, can change the</span>
+<span class="c"> * current BB. Note that we ignore the value computed by the body, but</span>
+<span class="c"> * don't allow an error *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">codegen_expr</span> <span class="n">body</span><span class="o">);</span>
+
+ <span class="c">(* Emit the step value. *)</span>
+ <span class="k">let</span> <span class="n">step_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">step</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">step</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">step</span>
+ <span class="c">(* If not specified, use 1.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">1</span><span class="o">.</span><span class="mi">0</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Compute the end condition. *)</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+ <span class="c">(* Reload, increment, and restore the alloca. This handles the case where</span>
+<span class="c"> * the body of the loop mutates the variable. *)</span>
+ <span class="k">let</span> <span class="n">cur_var</span> <span class="o">=</span> <span class="n">build_load</span> <span class="n">alloca</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">cur_var</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">next_var</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Convert condition to a bool by comparing equal to 0.0. *)</span>
+ <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">end_cond</span> <span class="n">zero</span> <span class="s2">"loopcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Create the "after loop" block and insert it. *)</span>
+ <span class="k">let</span> <span class="n">after_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"afterloop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+ <span class="c">(* Insert the conditional branch into the end of loop_end_bb. *)</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">end_cond</span> <span class="n">loop_bb</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Any new code will be inserted in after_bb. *)</span>
+ <span class="n">position_at_end</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="c">(* Restore the unshadowed variable. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">old_val</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">old_val</span> <span class="o">-></span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_val</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* for expr always returns 0.0. *)</span>
+ <span class="n">const_null</span> <span class="n">double_type</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="n">var_names</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">old_bindings</span> <span class="o">=</span> <span class="n">ref</span> <span class="bp">[]</span> <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Register all variables and emit their initializer. *)</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">-></span>
+ <span class="c">(* Emit the initializer before adding the variable to scope, this</span>
+<span class="c"> * prevents the initializer from referencing the variable itself, and</span>
+<span class="c"> * permits stuff like this:</span>
+<span class="c"> * var a = 1 in</span>
+<span class="c"> * var a = a in ... # refers to outer 'a'. *)</span>
+ <span class="k">let</span> <span class="n">init_val</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">init</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">init</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">init</span>
+ <span class="c">(* If not specified, use 0.0. *)</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span>
+ <span class="k">in</span>
+
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">init_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Remember the old variable binding so that we can restore the binding</span>
+<span class="c"> * when we unrecurse. *)</span>
+ <span class="k">begin</span>
+ <span class="k">try</span>
+ <span class="k">let</span> <span class="n">old_value</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="k">in</span>
+ <span class="n">old_bindings</span> <span class="o">:=</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">::</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+ <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* Remember this binding. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+ <span class="o">)</span> <span class="n">var_names</span><span class="o">;</span>
+
+ <span class="c">(* Codegen the body, now that all vars are in scope. *)</span>
+ <span class="k">let</span> <span class="n">body_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+ <span class="c">(* Pop all our variables from scope. *)</span>
+ <span class="nn">List</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_value</span>
+ <span class="o">)</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+
+ <span class="c">(* Return the body computation. *)</span>
+ <span class="n">body_val</span>
+
+<span class="k">let</span> <span class="n">codegen_proto</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span>
+ <span class="c">(* Make the function type: double(double,double) etc. *)</span>
+ <span class="k">let</span> <span class="n">doubles</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">make</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span><span class="o">)</span> <span class="n">double_type</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">ft</span> <span class="o">=</span> <span class="n">function_type</span> <span class="n">double_type</span> <span class="n">doubles</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">f</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">name</span> <span class="n">the_module</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">declare_function</span> <span class="n">name</span> <span class="n">ft</span> <span class="n">the_module</span>
+
+ <span class="c">(* If 'f' conflicted, there was already something named 'name'. If it</span>
+<span class="c"> * has a body, don't allow redefinition or reextern. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">f</span> <span class="o">-></span>
+ <span class="c">(* If 'f' already has a body, reject this. *)</span>
+ <span class="k">if</span> <span class="n">block_begin</span> <span class="n">f</span> <span class="o"><></span> <span class="nc">At_end</span> <span class="n">f</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function"</span><span class="o">);</span>
+
+ <span class="c">(* If 'f' took a different number of arguments, reject. *)</span>
+ <span class="k">if</span> <span class="n">element_type</span> <span class="o">(</span><span class="n">type_of</span> <span class="n">f</span><span class="o">)</span> <span class="o"><></span> <span class="n">ft</span> <span class="k">then</span>
+ <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function with different # args"</span><span class="o">);</span>
+ <span class="n">f</span>
+ <span class="k">in</span>
+
+ <span class="c">(* Set names for all arguments. *)</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">a</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">n</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+ <span class="n">set_value_name</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+ <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">f</span><span class="o">);</span>
+ <span class="n">f</span>
+
+<span class="c">(* Create an alloca for each argument and register the argument in the symbol</span>
+<span class="c"> * table so that references to it will succeed. *)</span>
+<span class="k">let</span> <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span> <span class="o">=</span>
+ <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span> <span class="n">args</span>
+ <span class="k">in</span>
+ <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">ai</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">var_name</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+ <span class="c">(* Create an alloca for this variable. *)</span>
+ <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+ <span class="c">(* Store the initial value into the alloca. *)</span>
+ <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">ai</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+ <span class="c">(* Add arguments to variable symbol table. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+ <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">the_function</span><span class="o">)</span>
+
+<span class="k">let</span> <span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="k">function</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">proto</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">clear</span> <span class="n">named_values</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">codegen_proto</span> <span class="n">proto</span> <span class="k">in</span>
+
+ <span class="c">(* If this is an operator, install it. *)</span>
+ <span class="k">begin</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">prec</span><span class="o">)</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">op</span> <span class="o">=</span> <span class="n">name</span><span class="o">.[</span><span class="nn">String</span><span class="p">.</span><span class="n">length</span> <span class="n">name</span> <span class="o">-</span> <span class="mi">1</span><span class="o">]</span> <span class="k">in</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="n">op</span> <span class="n">prec</span><span class="o">;</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="bp">()</span>
+ <span class="k">end</span><span class="o">;</span>
+
+ <span class="c">(* Create a new basic block to start insertion into. *)</span>
+ <span class="k">let</span> <span class="n">bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"entry"</span> <span class="n">the_function</span> <span class="k">in</span>
+ <span class="n">position_at_end</span> <span class="n">bb</span> <span class="n">builder</span><span class="o">;</span>
+
+ <span class="k">try</span>
+ <span class="c">(* Add all arguments to the symbol table and create their allocas. *)</span>
+ <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span><span class="o">;</span>
+
+ <span class="k">let</span> <span class="n">ret_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+ <span class="c">(* Finish off the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="n">build_ret</span> <span class="n">ret_val</span> <span class="n">builder</span> <span class="k">in</span>
+
+ <span class="c">(* Validate the generated code, checking for consistency. *)</span>
+ <span class="nn">Llvm_analysis</span><span class="p">.</span><span class="n">assert_valid_function</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* Optimize the function. *)</span>
+ <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="n">the_fpm</span> <span class="k">in</span>
+
+ <span class="n">the_function</span>
+ <span class="k">with</span> <span class="n">e</span> <span class="o">-></span>
+ <span class="n">delete_function</span> <span class="n">the_function</span><span class="o">;</span>
+ <span class="k">raise</span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>toplevel.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Top-Level parsing and JIT Driver</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+
+<span class="c">(* top ::= definition | external | expression | ';' *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span> <span class="o">=</span>
+ <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+
+ <span class="c">(* ignore top-level semicolons. *)</span>
+ <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">';'</span><span class="o">)</span> <span class="o">-></span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+
+ <span class="o">|</span> <span class="nc">Some</span> <span class="n">token</span> <span class="o">-></span>
+ <span class="k">begin</span>
+ <span class="k">try</span> <span class="k">match</span> <span class="n">token</span> <span class="k">with</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_definition</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a function definition."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span> <span class="o">-></span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_extern</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed an extern."</span><span class="o">;</span>
+ <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_proto</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+ <span class="c">(* Evaluate a top-level expression into an anonymous function. *)</span>
+ <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_toplevel</span> <span class="n">stream</span> <span class="k">in</span>
+ <span class="n">print_endline</span> <span class="s2">"parsed a top-level expr"</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span> <span class="k">in</span>
+ <span class="n">dump_value</span> <span class="n">the_function</span><span class="o">;</span>
+
+ <span class="c">(* JIT the function, returning a function pointer. *)</span>
+ <span class="k">let</span> <span class="n">result</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="o">[||]</span>
+ <span class="n">the_execution_engine</span> <span class="k">in</span>
+
+ <span class="n">print_string</span> <span class="s2">"Evaluated to "</span><span class="o">;</span>
+ <span class="n">print_float</span> <span class="o">(</span><span class="nn">GenericValue</span><span class="p">.</span><span class="n">as_float</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">double_type</span> <span class="n">result</span><span class="o">);</span>
+ <span class="n">print_newline</span> <span class="bp">()</span><span class="o">;</span>
+ <span class="k">with</span> <span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">|</span> <span class="nn">Codegen</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">-></span>
+ <span class="c">(* Skip token for error recovery. *)</span>
+ <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+ <span class="n">print_endline</span> <span class="n">s</span><span class="o">;</span>
+ <span class="k">end</span><span class="o">;</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+</pre></div>
+</div>
+</dd>
+<dt>toy.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Main driver code.</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+<span class="k">open</span> <span class="nc">Llvm_target</span>
+<span class="k">open</span> <span class="nc">Llvm_scalar_opts</span>
+
+<span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+ <span class="n">ignore</span> <span class="o">(</span><span class="n">initialize_native_target</span> <span class="bp">()</span><span class="o">);</span>
+
+ <span class="c">(* Install standard binary operators.</span>
+<span class="c"> * 1 is the lowest precedence. *)</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'='</span> <span class="mi">2</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+ <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'*'</span> <span class="mi">40</span><span class="o">;</span> <span class="c">(* highest. *)</span>
+
+ <span class="c">(* Prime the first token. *)</span>
+ <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+ <span class="k">let</span> <span class="n">stream</span> <span class="o">=</span> <span class="nn">Lexer</span><span class="p">.</span><span class="n">lex</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="n">of_channel</span> <span class="n">stdin</span><span class="o">)</span> <span class="k">in</span>
+
+ <span class="c">(* Create the JIT. *)</span>
+ <span class="k">let</span> <span class="n">the_execution_engine</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">create</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+ <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+ <span class="c">(* Set up the optimizer pipeline. Start with registering info about how the</span>
+<span class="c"> * target lays out data structures. *)</span>
+ <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Promote allocas to registers. *)</span>
+ <span class="n">add_memory_to_register_promotion</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+ <span class="n">add_instruction_combination</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* reassociate expressions. *)</span>
+ <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Eliminate Common SubExpressions. *)</span>
+ <span class="n">add_gvn</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="c">(* Simplify the control flow graph (deleting unreachable blocks, etc). *)</span>
+ <span class="n">add_cfg_simplification</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+ <span class="n">ignore</span> <span class="o">(</span><span class="nn">PassManager</span><span class="p">.</span><span class="n">initialize</span> <span class="n">the_fpm</span><span class="o">);</span>
+
+ <span class="c">(* Run the main "interpreter loop" now. *)</span>
+ <span class="nn">Toplevel</span><span class="p">.</span><span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span><span class="o">;</span>
+
+ <span class="c">(* Print out all the generated code. *)</span>
+ <span class="n">dump_module</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span>
+<span class="o">;;</span>
+
+<span class="n">main</span> <span class="bp">()</span>
+</pre></div>
+</div>
+</dd>
+<dt>bindings.c</dt>
+<dd><div class="first last highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="cm">/* putchard - putchar that takes a double and returns 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">putchard</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">putchar</span><span class="p">((</span><span class="kt">char</span><span class="p">)</span><span class="n">X</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="cm">/* printd - printf that takes a double prints it as "%f\n", returning 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">printd</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"%f</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">X</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+<p><a class="reference external" href="OCamlLangImpl8.html">Next: Conclusion and other useful LLVM tidbits</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl8.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl8.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl8.html (added)
+++ www-releases/trunk/6.0.1/docs/tutorial/OCamlLangImpl8.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,353 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>8. Kaleidoscope: Conclusion and other useful LLVM tidbits — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+ <link rel="next" title="1. Building a JIT: Starting out with KaleidoscopeJIT" href="BuildingAJIT1.html" />
+ <link rel="prev" title="7. Kaleidoscope: Extending the Language: Mutable Variables" href="OCamlLangImpl7.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="BuildingAJIT1.html" title="1. Building a JIT: Starting out with KaleidoscopeJIT"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="kaleidoscope-conclusion-and-other-useful-llvm-tidbits">
+<h1>8. Kaleidoscope: Conclusion and other useful LLVM tidbits<a class="headerlink" href="#kaleidoscope-conclusion-and-other-useful-llvm-tidbits" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#tutorial-conclusion" id="id2">Tutorial Conclusion</a></li>
+<li><a class="reference internal" href="#properties-of-the-llvm-ir" id="id3">Properties of the LLVM IR</a><ul>
+<li><a class="reference internal" href="#target-independence" id="id4">Target Independence</a></li>
+<li><a class="reference internal" href="#safety-guarantees" id="id5">Safety Guarantees</a></li>
+<li><a class="reference internal" href="#language-specific-optimizations" id="id6">Language-Specific Optimizations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tips-and-tricks" id="id7">Tips and Tricks</a><ul>
+<li><a class="reference internal" href="#implementing-portable-offsetof-sizeof" id="id8">Implementing portable offsetof/sizeof</a></li>
+<li><a class="reference internal" href="#garbage-collected-stack-frames" id="id9">Garbage Collected Stack Frames</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="tutorial-conclusion">
+<h2><a class="toc-backref" href="#id2">8.1. Tutorial Conclusion</a><a class="headerlink" href="#tutorial-conclusion" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to the final chapter of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. In the course of this tutorial, we have
+grown our little Kaleidoscope language from being a useless toy, to
+being a semi-interesting (but probably still useless) toy. :)</p>
+<p>It is interesting to see how far we’ve come, and how little code it has
+taken. We built the entire lexer, parser, AST, code generator, and an
+interactive run-loop (with a JIT!) by-hand in under 700 lines of
+(non-comment/non-blank) code.</p>
+<p>Our little language supports a couple of interesting features: it
+supports user defined binary and unary operators, it uses JIT
+compilation for immediate evaluation, and it supports a few control flow
+constructs with SSA construction.</p>
+<p>Part of the idea of this tutorial was to show you how easy and fun it
+can be to define, build, and play with languages. Building a compiler
+need not be a scary or mystical process! Now that you’ve seen some of
+the basics, I strongly encourage you to take the code and hack on it.
+For example, try adding:</p>
+<ul class="simple">
+<li><strong>global variables</strong> - While global variables have questional value
+in modern software engineering, they are often useful when putting
+together quick little hacks like the Kaleidoscope compiler itself.
+Fortunately, our current setup makes it very easy to add global
+variables: just have value lookup check to see if an unresolved
+variable is in the global variable symbol table before rejecting it.
+To create a new global variable, make an instance of the LLVM
+<tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class.</li>
+<li><strong>typed variables</strong> - Kaleidoscope currently only supports variables
+of type double. This gives the language a very nice elegance, because
+only supporting one type means that you never have to specify types.
+Different languages have different ways of handling this. The easiest
+way is to require the user to specify types for every variable
+definition, and record the type of the variable in the symbol table
+along with its Value*.</li>
+<li><strong>arrays, structs, vectors, etc</strong> - Once you add types, you can start
+extending the type system in all sorts of interesting ways. Simple
+arrays are very easy and are quite useful for many different
+applications. Adding them is mostly an exercise in learning how the
+LLVM <a class="reference external" href="../LangRef.html#getelementptr-instruction">getelementptr</a> instruction
+works: it is so nifty/unconventional, it <a class="reference external" href="../GetElementPtr.html">has its own
+FAQ</a>! If you add support for recursive types
+(e.g. linked lists), make sure to read the <a class="reference external" href="../ProgrammersManual.html#TypeResolve">section in the LLVM
+Programmer’s Manual</a> that
+describes how to construct them.</li>
+<li><strong>standard runtime</strong> - Our current language allows the user to access
+arbitrary external functions, and we use it for things like “printd”
+and “putchard”. As you extend the language to add higher-level
+constructs, often these constructs make the most sense if they are
+lowered to calls into a language-supplied runtime. For example, if
+you add hash tables to the language, it would probably make sense to
+add the routines to a runtime, instead of inlining them all the way.</li>
+<li><strong>memory management</strong> - Currently we can only access the stack in
+Kaleidoscope. It would also be useful to be able to allocate heap
+memory, either with calls to the standard libc malloc/free interface
+or with a garbage collector. If you would like to use garbage
+collection, note that LLVM fully supports <a class="reference external" href="../GarbageCollection.html">Accurate Garbage
+Collection</a> including algorithms that
+move objects and need to scan/update the stack.</li>
+<li><strong>debugger support</strong> - LLVM supports generation of <a class="reference external" href="../SourceLevelDebugging.html">DWARF Debug
+info</a> which is understood by common
+debuggers like GDB. Adding support for debug info is fairly
+straightforward. The best way to understand it is to compile some
+C/C++ code with “<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-g</span> <span class="pre">-O0</span></tt>” and taking a look at what it
+produces.</li>
+<li><strong>exception handling support</strong> - LLVM supports generation of <a class="reference external" href="../ExceptionHandling.html">zero
+cost exceptions</a> which interoperate with
+code compiled in other languages. You could also generate code by
+implicitly making every function return an error value and checking
+it. You could also make explicit use of setjmp/longjmp. There are
+many different ways to go here.</li>
+<li><strong>object orientation, generics, database access, complex numbers,
+geometric programming, ...</strong> - Really, there is no end of crazy
+features that you can add to the language.</li>
+<li><strong>unusual domains</strong> - We’ve been talking about applying LLVM to a
+domain that many people are interested in: building a compiler for a
+specific language. However, there are many other domains that can use
+compiler technology that are not typically considered. For example,
+LLVM has been used to implement OpenGL graphics acceleration,
+translate C++ code to ActionScript, and many other cute and clever
+things. Maybe you will be the first to JIT compile a regular
+expression interpreter into native code with LLVM?</li>
+</ul>
+<p>Have fun - try doing something crazy and unusual. Building a language
+like everyone else always has, is much less fun than trying something a
+little crazy or off the wall and seeing how it turns out. If you get
+stuck or want to talk about it, feel free to email the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev mailing
+list</a>: it has lots
+of people who are interested in languages and are often willing to help
+out.</p>
+<p>Before we end this tutorial, I want to talk about some “tips and tricks”
+for generating LLVM IR. These are some of the more subtle things that
+may not be obvious, but are very useful if you want to take advantage of
+LLVM’s capabilities.</p>
+</div>
+<div class="section" id="properties-of-the-llvm-ir">
+<h2><a class="toc-backref" href="#id3">8.2. Properties of the LLVM IR</a><a class="headerlink" href="#properties-of-the-llvm-ir" title="Permalink to this headline">¶</a></h2>
+<p>We have a couple common questions about code in the LLVM IR form - lets
+just get these out of the way right now, shall we?</p>
+<div class="section" id="target-independence">
+<h3><a class="toc-backref" href="#id4">8.2.1. Target Independence</a><a class="headerlink" href="#target-independence" title="Permalink to this headline">¶</a></h3>
+<p>Kaleidoscope is an example of a “portable language”: any program written
+in Kaleidoscope will work the same way on any target that it runs on.
+Many other languages have this property, e.g. lisp, java, haskell,
+javascript, python, etc (note that while these languages are portable,
+not all their libraries are).</p>
+<p>One nice aspect of LLVM is that it is often capable of preserving target
+independence in the IR: you can take the LLVM IR for a
+Kaleidoscope-compiled program and run it on any target that LLVM
+supports, even emitting C code and compiling that on targets that LLVM
+doesn’t support natively. You can trivially tell that the Kaleidoscope
+compiler generates target-independent code because it never queries for
+any target-specific information when generating code.</p>
+<p>The fact that LLVM provides a compact, target-independent,
+representation for code gets a lot of people excited. Unfortunately,
+these people are usually thinking about C or a language from the C
+family when they are asking questions about language portability. I say
+“unfortunately”, because there is really no way to make (fully general)
+C code portable, other than shipping the source code around (and of
+course, C source code is not actually portable in general either - ever
+port a really old application from 32- to 64-bits?).</p>
+<p>The problem with C (again, in its full generality) is that it is heavily
+laden with target specific assumptions. As one simple example, the
+preprocessor often destructively removes target-independence from the
+code when it processes the input text:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#ifdef __i386__</span>
+ <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="cp">#else</span>
+ <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>While it is possible to engineer more and more complex solutions to
+problems like this, it cannot be solved in full generality in a way that
+is better than shipping the actual source code.</p>
+<p>That said, there are interesting subsets of C that can be made portable.
+If you are willing to fix primitive types to a fixed size (say int =
+32-bits, and long = 64-bits), don’t care about ABI compatibility with
+existing binaries, and are willing to give up some other minor features,
+you can have portable code. This can make sense for specialized domains
+such as an in-kernel language.</p>
+</div>
+<div class="section" id="safety-guarantees">
+<h3><a class="toc-backref" href="#id5">8.2.2. Safety Guarantees</a><a class="headerlink" href="#safety-guarantees" title="Permalink to this headline">¶</a></h3>
+<p>Many of the languages above are also “safe” languages: it is impossible
+for a program written in Java to corrupt its address space and crash the
+process (assuming the JVM has no bugs). Safety is an interesting
+property that requires a combination of language design, runtime
+support, and often operating system support.</p>
+<p>It is certainly possible to implement a safe language in LLVM, but LLVM
+IR does not itself guarantee safety. The LLVM IR allows unsafe pointer
+casts, use after free bugs, buffer over-runs, and a variety of other
+problems. Safety needs to be implemented as a layer on top of LLVM and,
+conveniently, several groups have investigated this. Ask on the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev
+mailing list</a> if
+you are interested in more details.</p>
+</div>
+<div class="section" id="language-specific-optimizations">
+<h3><a class="toc-backref" href="#id6">8.2.3. Language-Specific Optimizations</a><a class="headerlink" href="#language-specific-optimizations" title="Permalink to this headline">¶</a></h3>
+<p>One thing about LLVM that turns off many people is that it does not
+solve all the world’s problems in one system (sorry ‘world hunger’,
+someone else will have to solve you some other day). One specific
+complaint is that people perceive LLVM as being incapable of performing
+high-level language-specific optimization: LLVM “loses too much
+information”.</p>
+<p>Unfortunately, this is really not the place to give you a full and
+unified version of “Chris Lattner’s theory of compiler design”. Instead,
+I’ll make a few observations:</p>
+<p>First, you’re right that LLVM does lose information. For example, as of
+this writing, there is no way to distinguish in the LLVM IR whether an
+SSA-value came from a C “int” or a C “long” on an ILP32 machine (other
+than debug info). Both get compiled down to an ‘i32’ value and the
+information about what it came from is lost. The more general issue
+here, is that the LLVM type system uses “structural equivalence” instead
+of “name equivalence”. Another place this surprises people is if you
+have two types in a high-level language that have the same structure
+(e.g. two different structs that have a single int field): these types
+will compile down into a single LLVM type and it will be impossible to
+tell what it came from.</p>
+<p>Second, while LLVM does lose information, LLVM is not a fixed target: we
+continue to enhance and improve it in many different ways. In addition
+to adding new features (LLVM did not always support exceptions or debug
+info), we also extend the IR to capture important information for
+optimization (e.g. whether an argument is sign or zero extended,
+information about pointers aliasing, etc). Many of the enhancements are
+user-driven: people want LLVM to include some specific feature, so they
+go ahead and extend it.</p>
+<p>Third, it is <em>possible and easy</em> to add language-specific optimizations,
+and you have a number of choices in how to do it. As one trivial
+example, it is easy to add language-specific optimization passes that
+“know” things about code compiled for a language. In the case of the C
+family, there is an optimization pass that “knows” about the standard C
+library functions. If you call “exit(0)” in main(), it knows that it is
+safe to optimize that into “return 0;” because C specifies what the
+‘exit’ function does.</p>
+<p>In addition to simple library knowledge, it is possible to embed a
+variety of other language-specific information into the LLVM IR. If you
+have a specific need and run into a wall, please bring the topic up on
+the llvm-dev list. At the very worst, you can always treat LLVM as if it
+were a “dumb code generator” and implement the high-level optimizations
+you desire in your front-end, on the language-specific AST.</p>
+</div>
+</div>
+<div class="section" id="tips-and-tricks">
+<h2><a class="toc-backref" href="#id7">8.3. Tips and Tricks</a><a class="headerlink" href="#tips-and-tricks" title="Permalink to this headline">¶</a></h2>
+<p>There is a variety of useful tips and tricks that you come to know after
+working on/with LLVM that aren’t obvious at first glance. Instead of
+letting everyone rediscover them, this section talks about some of these
+issues.</p>
+<div class="section" id="implementing-portable-offsetof-sizeof">
+<h3><a class="toc-backref" href="#id8">8.3.1. Implementing portable offsetof/sizeof</a><a class="headerlink" href="#implementing-portable-offsetof-sizeof" title="Permalink to this headline">¶</a></h3>
+<p>One interesting thing that comes up, if you are trying to keep the code
+generated by your compiler “target independent”, is that you often need
+to know the size of some LLVM type or the offset of some field in an
+llvm structure. For example, you might need to pass the size of a type
+into a function that allocates memory.</p>
+<p>Unfortunately, this can vary widely across targets: for example the
+width of a pointer is trivially target-specific. However, there is a
+<a class="reference external" href="http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt">clever way to use the getelementptr
+instruction</a>
+that allows you to compute this in a portable way.</p>
+</div>
+<div class="section" id="garbage-collected-stack-frames">
+<h3><a class="toc-backref" href="#id9">8.3.2. Garbage Collected Stack Frames</a><a class="headerlink" href="#garbage-collected-stack-frames" title="Permalink to this headline">¶</a></h3>
+<p>Some languages want to explicitly manage their stack frames, often so
+that they are garbage collected or to allow easy implementation of
+closures. There are often better ways to implement these features than
+explicit stack frames, but <a class="reference external" href="http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt">LLVM does support
+them,</a>
+if you want. It requires your front-end to convert the code into
+<a class="reference external" href="http://en.wikipedia.org/wiki/Continuation-passing_style">Continuation Passing
+Style</a> and
+the use of tail calls (which LLVM also supports).</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="BuildingAJIT1.html" title="1. Building a JIT: Starting out with KaleidoscopeJIT"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/tutorial/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/tutorial/index.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/tutorial/index.html (added)
+++ www-releases/trunk/6.0.1/docs/tutorial/index.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,207 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Tutorial: Table of Contents — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="next" title="1. Kaleidoscope: Tutorial Introduction and the Lexer" href="LangImpl01.html" />
+ <link rel="prev" title="LLVM test-suite Guide" href="../TestSuiteMakefileGuide.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LangImpl01.html" title="1. Kaleidoscope: Tutorial Introduction and the Lexer"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../TestSuiteMakefileGuide.html" title="LLVM test-suite Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-tutorial-table-of-contents">
+<h1>LLVM Tutorial: Table of Contents<a class="headerlink" href="#llvm-tutorial-table-of-contents" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="kaleidoscope-implementing-a-language-with-llvm">
+<h2>Kaleidoscope: Implementing a Language with LLVM<a class="headerlink" href="#kaleidoscope-implementing-a-language-with-llvm" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl01.html">1. Kaleidoscope: Tutorial Introduction and the Lexer</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl02.html">2. Kaleidoscope: Implementing a Parser and AST</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl03.html">3. Kaleidoscope: Code generation to LLVM IR</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl04.html">4. Kaleidoscope: Adding JIT and Optimizer Support</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl05.html">5. Kaleidoscope: Extending the Language: Control Flow</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl06.html">6. Kaleidoscope: Extending the Language: User-defined Operators</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl07.html">7. Kaleidoscope: Extending the Language: Mutable Variables</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl08.html">8. Kaleidoscope: Compiling to Object Code</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl09.html">9. Kaleidoscope: Adding Debug Information</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl10.html">10. Kaleidoscope: Conclusion and other useful LLVM tidbits</a><ul class="simple">
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="kaleidoscope-implementing-a-language-with-llvm-in-objective-caml">
+<h2>Kaleidoscope: Implementing a Language with LLVM in Objective Caml<a class="headerlink" href="#kaleidoscope-implementing-a-language-with-llvm-in-objective-caml" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl1.html">1. Kaleidoscope: Tutorial Introduction and the Lexer</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl2.html">2. Kaleidoscope: Implementing a Parser and AST</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl3.html">3. Kaleidoscope: Code generation to LLVM IR</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl4.html">4. Kaleidoscope: Adding JIT and Optimizer Support</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl5.html">5. Kaleidoscope: Extending the Language: Control Flow</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl6.html">6. Kaleidoscope: Extending the Language: User-defined Operators</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl7.html">7. Kaleidoscope: Extending the Language: Mutable Variables</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl8.html">8. Kaleidoscope: Conclusion and other useful LLVM tidbits</a><ul class="simple">
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="building-a-jit-in-llvm">
+<h2>Building a JIT in LLVM<a class="headerlink" href="#building-a-jit-in-llvm" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="BuildingAJIT1.html">1. Building a JIT: Starting out with KaleidoscopeJIT</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="BuildingAJIT2.html">2. Building a JIT: Adding Optimizations – An introduction to ORC Layers</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="BuildingAJIT3.html">3. Building a JIT: Per-function Lazy Compilation</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="BuildingAJIT4.html">4. Building a JIT: Extreme Laziness - Using Compile Callbacks to JIT from ASTs</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="BuildingAJIT5.html">5. Building a JIT: Remote-JITing – Process Isolation and Laziness at a Distance</a><ul class="simple">
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="external-tutorials">
+<h2>External Tutorials<a class="headerlink" href="#external-tutorials" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><a class="reference external" href="http://jonathan2251.github.com/lbd/">Tutorial: Creating an LLVM Backend for the Cpu0 Architecture</a></dt>
+<dd>A step-by-step tutorial for developing an LLVM backend. Under
+active development at <a class="reference external" href="https://github.com/Jonathan2251/lbd">https://github.com/Jonathan2251/lbd</a> (please
+contribute!).</dd>
+<dt><a class="reference external" href="http://www.embecosm.com/appnotes/ean10/ean10-howto-llvmas-1.0.html">Howto: Implementing LLVM Integrated Assembler</a></dt>
+<dd>A simple guide for how to implement an LLVM integrated assembler for an
+architecture.</dd>
+</dl>
+</div>
+<div class="section" id="advanced-topics">
+<h2>Advanced Topics<a class="headerlink" href="#advanced-topics" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://llvm.org/pubs/2004-09-22-LCPCLLVMTutorial.html">Writing an Optimization for LLVM</a></li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LangImpl01.html" title="1. Kaleidoscope: Tutorial Introduction and the Lexer"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../TestSuiteMakefileGuide.html" title="LLVM test-suite Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/yaml2obj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/yaml2obj.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/yaml2obj.html (added)
+++ www-releases/trunk/6.0.1/docs/yaml2obj.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,308 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>yaml2obj — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="How to submit an LLVM bug report" href="HowToSubmitABug.html" />
+ <link rel="prev" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure" href="HowToAddABuilder.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="yaml2obj">
+<h1>yaml2obj<a class="headerlink" href="#yaml2obj" title="Permalink to this headline">¶</a></h1>
+<p>yaml2obj takes a YAML description of an object file and converts it to a binary
+file.</p>
+<blockquote>
+<div>$ yaml2obj input-file</div></blockquote>
+<p>Outputs the binary to stdout.</p>
+<div class="section" id="coff-syntax">
+<h2>COFF Syntax<a class="headerlink" href="#coff-syntax" title="Permalink to this headline">¶</a></h2>
+<p>Here’s a sample COFF file.</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">header</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">Machine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_FILE_MACHINE_I386</span> <span class="c1"># (0x14C)</span>
+
+<span class="l-Scalar-Plain">sections</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">.text</span>
+ <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SCN_CNT_CODE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_16BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_EXECUTE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_READ</span>
+ <span class="p-Indicator">]</span> <span class="c1"># 0x60500020</span>
+ <span class="l-Scalar-Plain">SectionData</span><span class="p-Indicator">:</span>
+ <span class="s">"</span><span class="se">\x83\xEC\x0C\xC7\x44\x24\x08\x00\x00\x00\x00\xC7\x04\x24\x00\x00\x00\x00\xE8\x00\x00\x00\x00\xE8\x00\x00\x00\x00\x8B\x44\x24\x08\x83\xC4\x0C\xC3</span><span class="s">"</span> <span class="c1"># |....D$.......$...............D$.....|</span>
+
+<span class="l-Scalar-Plain">symbols</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">.text</span>
+ <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+ <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+ <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_TYPE_NULL</span> <span class="c1"># (0)</span>
+ <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_DTYPE_NULL</span> <span class="c1"># (0)</span>
+ <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_CLASS_STATIC</span> <span class="c1"># (3)</span>
+ <span class="l-Scalar-Plain">NumberOfAuxSymbols</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+ <span class="l-Scalar-Plain">AuxiliaryData</span><span class="p-Indicator">:</span>
+ <span class="s">"</span><span class="se">\x24\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00</span><span class="s">"</span> <span class="c1"># |$.................|</span>
+
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">_main</span>
+ <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+ <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+ <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_TYPE_NULL</span> <span class="c1"># (0)</span>
+ <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_DTYPE_NULL</span> <span class="c1"># (0)</span>
+ <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_CLASS_EXTERNAL</span> <span class="c1"># (2)</span>
+</pre></div>
+</div>
+<p>Here’s a simplified <a class="reference external" href="http://www.kuwata-lab.com/kwalify/ruby/users-guide.html">Kwalify</a> schema with an extension to allow alternate types.</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+ <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">header</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+ <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">Machine</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">[</span> <span class="nv">IMAGE_FILE_MACHINE_UNKNOWN</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_AM33</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_AMD64</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_ARM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_ARMNT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_ARM64</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_EBC</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_I386</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_IA64</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_M32R</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPS16</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPSFPU</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPSFPU16</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_POWERPC</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_POWERPCFP</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_R4000</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH3</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH3DSP</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH4</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH5</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_THUMB</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_WCEMIPSV2</span>
+ <span class="p-Indicator">]}</span>
+ <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="p-Indicator">]</span>
+ <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+ <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">str</span>
+ <span class="l-Scalar-Plain">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_FILE_RELOCS_STRIPPED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_EXECUTABLE_IMAGE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LINE_NUMS_STRIPPED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LOCAL_SYMS_STRIPPED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_AGGRESSIVE_WS_TRIM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LARGE_ADDRESS_AWARE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_BYTES_REVERSED_LO</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_32BIT_MACHINE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_DEBUG_STRIPPED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_NET_RUN_FROM_SWAP</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_SYSTEM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_DLL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_UP_SYSTEM_ONLY</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_BYTES_REVERSED_HI</span>
+ <span class="p-Indicator">]</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">int</span>
+ <span class="l-Scalar-Plain">sections</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+ <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+ <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+ <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+ <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">str</span>
+ <span class="l-Scalar-Plain">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SCN_TYPE_NO_PAD</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_CODE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_INITIALIZED_DATA</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_UNINITIALIZED_DATA</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_OTHER</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_INFO</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_REMOVE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_COMDAT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_GPREL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_PURGEABLE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_16BIT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_LOCKED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_PRELOAD</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_1BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_2BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_4BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_8BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_16BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_32BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_64BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_128BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_256BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_512BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_1024BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_2048BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_4096BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_8192BYTES</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_NRELOC_OVFL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_DISCARDABLE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_NOT_CACHED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_NOT_PAGED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_SHARED</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_EXECUTE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_READ</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_WRITE</span>
+ <span class="p-Indicator">]</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">int</span>
+ <span class="l-Scalar-Plain">SectionData</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+ <span class="l-Scalar-Plain">symbols</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+ <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+ <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+ <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_TYPE_NULL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_VOID</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_CHAR</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_SHORT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_INT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_LONG</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_FLOAT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_DOUBLE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_STRUCT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_UNION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_ENUM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_MOE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_BYTE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_WORD</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_UINT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_DWORD</span>
+ <span class="p-Indicator">]}</span>
+ <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="p-Indicator">]</span>
+ <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_DTYPE_NULL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_POINTER</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_FUNCTION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_ARRAY</span>
+ <span class="p-Indicator">]}</span>
+ <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="p-Indicator">]</span>
+ <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_CLASS_END_OF_FUNCTION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_NULL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_AUTOMATIC</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_EXTERNAL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_STATIC</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_REGISTER</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_EXTERNAL_DEF</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_LABEL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNDEFINED_LABEL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_STRUCT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_ARGUMENT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_STRUCT_TAG</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_UNION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNION_TAG</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_TYPE_DEFINITION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNDEFINED_STATIC</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_ENUM_TAG</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_ENUM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_REGISTER_PARAM</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_BIT_FIELD</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_BLOCK</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_FUNCTION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_END_OF_STRUCT</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_FILE</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_SECTION</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_WEAK_EXTERNAL</span>
+ <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_CLR_TOKEN</span>
+ <span class="p-Indicator">]}</span>
+ <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+ <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/tools/clang/docs/AddressSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/tools/clang/docs/AddressSanitizer.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/tools/clang/docs/AddressSanitizer.html (added)
+++ www-releases/trunk/6.0.1/tools/clang/docs/AddressSanitizer.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,354 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>AddressSanitizer — Clang 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 6 documentation" href="index.html" />
+ <link rel="next" title="ThreadSanitizer" href="ThreadSanitizer.html" />
+ <link rel="prev" title="Thread Safety Analysis" href="ThreadSafetyAnalysis.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>AddressSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThreadSanitizer.html">ThreadSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="addresssanitizer">
+<h1>AddressSanitizer<a class="headerlink" href="#addresssanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a></li>
+<li><a class="reference internal" href="#symbolizing-the-reports" id="id4">Symbolizing the Reports</a></li>
+<li><a class="reference internal" href="#additional-checks" id="id5">Additional Checks</a><ul>
+<li><a class="reference internal" href="#initialization-order-checking" id="id6">Initialization order checking</a></li>
+<li><a class="reference internal" href="#memory-leak-detection" id="id7">Memory leak detection</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#issue-suppression" id="id8">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#suppressing-reports-in-external-libraries" id="id9">Suppressing Reports in External Libraries</a></li>
+<li><a class="reference internal" href="#conditional-compilation-with-has-feature-address-sanitizer" id="id10">Conditional Compilation with <tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a></li>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-address" id="id11">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("address")))</span></tt></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id12">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#suppressing-memory-leaks" id="id13">Suppressing memory leaks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#limitations" id="id14">Limitations</a></li>
+<li><a class="reference internal" href="#supported-platforms" id="id15">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id16">Current Status</a></li>
+<li><a class="reference internal" href="#more-information" id="id17">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is a fast memory error detector. It consists of a compiler
+instrumentation module and a run-time library. The tool can detect the
+following types of bugs:</p>
+<ul class="simple">
+<li>Out-of-bounds accesses to heap, stack and globals</li>
+<li>Use-after-free</li>
+<li>Use-after-return (runtime flag <cite>ASAN_OPTIONS=detect_stack_use_after_return=1</cite>)</li>
+<li>Use-after-scope (clang flag <cite>-fsanitize-address-use-after-scope</cite>)</li>
+<li>Double-free, invalid free</li>
+<li>Memory leaks (experimental)</li>
+</ul>
+<p>Typical slowdown introduced by AddressSanitizer is <strong>2x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt> flag. The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use <tt class="docutils literal"><span class="pre">clang</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) for the final link step. When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+<tt class="docutils literal"><span class="pre">-Wl,-z,defs</span></tt> may cause link errors (don’t use it with AddressSanitizer). To
+get a reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher. To get nicer stack traces
+in error messages add <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt>. To get perfect stack traces
+you may need to disable inlining (just use <tt class="docutils literal"><span class="pre">-O1</span></tt>) and tail call elimination
+(<tt class="docutils literal"><span class="pre">-fno-optimize-sibling-calls</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat example_UseAfterFree.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go"> int *array = new int[100];</span>
+<span class="go"> delete [] array;</span>
+<span class="go"> return array[argc]; // BOOM</span>
+<span class="go">}</span>
+
+<span class="gp">#</span> Compile and link
+<span class="gp">%</span> clang++ -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer example_UseAfterFree.cc
+</pre></div>
+</div>
+<p>or:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Compile
+<span class="gp">%</span> clang++ -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+<span class="gp">#</span> Link
+<span class="gp">%</span> clang++ -g -fsanitize<span class="o">=</span>address example_UseAfterFree.o
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:</p>
+<ul class="simple">
+<li>This approach allows AddressSanitizer to produce faster and smaller generated code
+(both by ~5%).</li>
+<li>Fixing bugs becomes unavoidable. AddressSanitizer does not produce
+false alarms. Once a memory corruption occurs, the program is in an inconsistent
+state, which could lead to confusing results and potentially misleading
+subsequent reports.</li>
+</ul>
+<p>If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set <tt class="docutils literal"><span class="pre">DYLD_INSERT_LIBRARIES</span></tt> environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+<tt class="docutils literal"><span class="pre">asan</span></tt> in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.</p>
+</div>
+<div class="section" id="symbolizing-the-reports">
+<h2><a class="toc-backref" href="#id4">Symbolizing the Reports</a><a class="headerlink" href="#symbolizing-the-reports" title="Permalink to this headline">¶</a></h2>
+<p>To make AddressSanitizer symbolize its output
+you need to set the <tt class="docutils literal"><span class="pre">ASAN_SYMBOLIZER_PATH</span></tt> environment variable to point to
+the <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary (or make sure <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> is in your
+<tt class="docutils literal"><span class="pre">$PATH</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_SYMBOLIZER_PATH</span><span class="o">=</span>/usr/local/bin/llvm-symbolizer ./a.out
+<span class="go">==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8</span>
+<span class="go">READ of size 4 at 0x7f7ddab8c084 thread T0</span>
+<span class="go"> #0 0x403c8c in main example_UseAfterFree.cc:4</span>
+<span class="go"> #1 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)</span>
+<span class="go">freed by thread T0 here:</span>
+<span class="go"> #0 0x404704 in operator delete[](void*) ??:0</span>
+<span class="go"> #1 0x403c53 in main example_UseAfterFree.cc:4</span>
+<span class="go"> #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">previously allocated by thread T0 here:</span>
+<span class="go"> #0 0x404544 in operator new[](unsigned long) ??:0</span>
+<span class="go"> #1 0x403c43 in main example_UseAfterFree.cc:2</span>
+<span class="go"> #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">==9442== ABORTING</span>
+</pre></div>
+</div>
+<p>If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=symbolize=0</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">symbolize</span><span class="o">=</span>0 ./a.out 2> log
+<span class="gp">%</span> projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+<span class="go">==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8</span>
+<span class="go">READ of size 4 at 0x7f7ddab8c084 thread T0</span>
+<span class="go"> #0 0x403c8c in main example_UseAfterFree.cc:4</span>
+<span class="go"> #1 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">...</span>
+</pre></div>
+</div>
+<p>Note that on OS X you may need to run <tt class="docutils literal"><span class="pre">dsymutil</span></tt> on your binary to have the
+file:line info in the AddressSanitizer reports.</p>
+</div>
+<div class="section" id="additional-checks">
+<h2><a class="toc-backref" href="#id5">Additional Checks</a><a class="headerlink" href="#additional-checks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="initialization-order-checking">
+<h3><a class="toc-backref" href="#id6">Initialization order checking</a><a class="headerlink" href="#initialization-order-checking" title="Permalink to this headline">¶</a></h3>
+<p>AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+<tt class="docutils literal"><span class="pre">ASAN_OPTIONS=check_initialization_order=1</span></tt>.</p>
+<p>Note that this option is not supported on OS X.</p>
+</div>
+<div class="section" id="memory-leak-detection">
+<h3><a class="toc-backref" href="#id7">Memory leak detection</a><a class="headerlink" href="#memory-leak-detection" title="Permalink to this headline">¶</a></h3>
+<p>For more information on leak detector in AddressSanitizer, see
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>. The leak detection is turned on by default on Linux,
+and can be enabled using <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=detect_leaks=1</span></tt> on OS X;
+however, it is not yet supported on other platforms.</p>
+</div>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id8">Issue Suppression</a><a class="headerlink" href="#issue-suppression" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!</p>
+<div class="section" id="suppressing-reports-in-external-libraries">
+<h3><a class="toc-backref" href="#id9">Suppressing Reports in External Libraries</a><a class="headerlink" href="#suppressing-reports-in-external-libraries" title="Permalink to this headline">¶</a></h3>
+<p>Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the <tt class="docutils literal"><span class="pre">ASAN_OPTIONS</span></tt> environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">suppressions</span><span class="o">=</span>MyASan.supp
+</pre></div>
+</div>
+<p>Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.</p>
+<div class="highlight-bash"><div class="highlight"><pre>interceptor_via_fun:NameOfCFunctionToSuppress
+interceptor_via_fun:-<span class="o">[</span>ClassName objCMethodToSuppress:<span class="o">]</span>
+interceptor_via_lib:NameOfTheLibraryToSuppress
+</pre></div>
+</div>
+</div>
+<div class="section" id="conditional-compilation-with-has-feature-address-sanitizer">
+<h3><a class="toc-backref" href="#id10">Conditional Compilation with <tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a><a class="headerlink" href="#conditional-compilation-with-has-feature-address-sanitizer" title="Permalink to this headline">¶</a></h3>
+<p>In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp"># if __has_feature(address_sanitizer)</span>
+<span class="cp">// code that builds only under AddressSanitizer</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="disabling-instrumentation-with-attribute-no-sanitize-address">
+<h3><a class="toc-backref" href="#id11">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("address")))</span></tt></a><a class="headerlink" href="#disabling-instrumentation-with-attribute-no-sanitize-address" title="Permalink to this headline">¶</a></h3>
+<p>Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("address")))</span></tt> (which has
+deprecated synonyms <cite>no_sanitize_address</cite> and <cite>no_address_safety_analysis</cite>) to
+disable instrumentation of a particular function. This attribute may not be
+supported by other compilers, so we suggest to use it together with
+<tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id12">Suppressing Errors in Recompiled Code (Blacklist)</a><a class="headerlink" href="#suppressing-errors-in-recompiled-code-blacklist" title="Permalink to this headline">¶</a></h3>
+<p>AddressSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces <tt class="docutils literal"><span class="pre">global</span></tt> and <tt class="docutils literal"><span class="pre">type</span></tt> entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).</p>
+<p>You may use an <tt class="docutils literal"><span class="pre">init</span></tt> category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Suppress error reports for code in a file or in a function:</span>
+src:bad_file.cpp
+<span class="c"># Ignore all functions with names containing MyFooBar:</span>
+fun:*MyFooBar*
+<span class="c"># Disable out-of-bound checks for global:</span>
+global:bad_array
+<span class="c"># Disable out-of-bound checks for global instances of a given class ...</span>
+<span class="nb">type</span>:Namespace::BadClassName
+<span class="c"># ... or a given struct. Use wildcard to deal with anonymous namespace.</span>
+<span class="nb">type</span>:Namespace2::*::BadStructName
+<span class="c"># Disable initialization-order checks for globals:</span>
+global:bad_init_global<span class="o">=</span>init
+<span class="nb">type</span>:*BadInitClassSubstring*<span class="o">=</span>init
+src:bad/init/files/*<span class="o">=</span>init
+</pre></div>
+</div>
+</div>
+<div class="section" id="suppressing-memory-leaks">
+<h3><a class="toc-backref" href="#id13">Suppressing memory leaks</a><a class="headerlink" href="#suppressing-memory-leaks" title="Permalink to this headline">¶</a></h3>
+<p>Memory leak reports produced by <a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a> (if it is run as a part
+of AddressSanitizer) can be suppressed by a separate file passed as</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">LSAN_OPTIONS</span><span class="o">=</span><span class="nv">suppressions</span><span class="o">=</span>MyLSan.supp
+</pre></div>
+</div>
+<p>which contains lines of the form <cite>leak:<pattern></cite>. Memory leak will be
+suppressed if pattern matches any function name, source file name, or
+library name in the symbolized stack trace of the leak report. See
+<a class="reference external" href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions">full documentation</a>
+for more details.</p>
+</div>
+</div>
+<div class="section" id="limitations">
+<h2><a class="toc-backref" href="#id14">Limitations</a><a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>AddressSanitizer uses more real memory than a native run. Exact overhead
+depends on the allocations sizes. The smaller the allocations you make the
+bigger the overhead is.</li>
+<li>AddressSanitizer uses more stack memory. We have seen up to 3x increase.</li>
+<li>On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+virtual address space. This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as
+usually expected.</li>
+<li>Static linking is not supported.</li>
+</ul>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id15">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is supported on:</p>
+<ul class="simple">
+<li>Linux i386/x86_64 (tested on Ubuntu 12.04)</li>
+<li>OS X 10.7 - 10.11 (i386/x86_64)</li>
+<li>iOS Simulator</li>
+<li>Android ARM</li>
+<li>FreeBSD i386/x86_64 (tested on FreeBSD 11-current)</li>
+</ul>
+<p>Ports to various other platforms are in progress.</p>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id16">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is fully functional on supported platforms starting from LLVM
+3.1. The test suite is integrated into CMake build and can be run with <tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">check-asan</span></tt> command.</p>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id17">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://github.com/google/sanitizers/wiki/AddressSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizer</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThreadSanitizer.html">ThreadSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/tools/clang/docs/AttributeReference.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/tools/clang/docs/AttributeReference.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/tools/clang/docs/AttributeReference.html (added)
+++ www-releases/trunk/6.0.1/tools/clang/docs/AttributeReference.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,6704 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Attributes in Clang — Clang 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 6 documentation" href="index.html" />
+ <link rel="next" title="Diagnostic flags in Clang" href="DiagnosticsReference.html" />
+ <link rel="prev" title="Clang command line argument reference" href="ClangCommandLineReference.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Attributes in Clang</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ClangCommandLineReference.html">Clang command line argument reference</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="attributes-in-clang">
+<h1>Attributes in Clang<a class="headerlink" href="#attributes-in-clang" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a></li>
+<li><a class="reference internal" href="#function-attributes" id="id6">Function Attributes</a><ul>
+<li><a class="reference internal" href="#pragma-omp-declare-simd" id="id7">#pragma omp declare simd</a></li>
+<li><a class="reference internal" href="#pragma-omp-declare-target" id="id8">#pragma omp declare target</a></li>
+<li><a class="reference internal" href="#noreturn" id="id9">_Noreturn</a></li>
+<li><a class="reference internal" href="#abi-tag-gnu-abi-tag" id="id10">abi_tag (gnu::abi_tag)</a></li>
+<li><a class="reference internal" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" id="id11">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a></li>
+<li><a class="reference internal" href="#alloc-align-gnu-alloc-align" id="id12">alloc_align (gnu::alloc_align)</a></li>
+<li><a class="reference internal" href="#alloc-size-gnu-alloc-size" id="id13">alloc_size (gnu::alloc_size)</a></li>
+<li><a class="reference internal" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" id="id14">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a></li>
+<li><a class="reference internal" href="#assume-aligned-gnu-assume-aligned" id="id15">assume_aligned (gnu::assume_aligned)</a></li>
+<li><a class="reference internal" href="#availability" id="id16">availability</a></li>
+<li><a class="reference internal" href="#carries-dependency" id="id17">carries_dependency</a></li>
+<li><a class="reference internal" href="#convergent-clang-convergent" id="id18">convergent (clang::convergent)</a></li>
+<li><a class="reference internal" href="#deprecated-gnu-deprecated" id="id19">deprecated (gnu::deprecated)</a></li>
+<li><a class="reference internal" href="#diagnose-if" id="id20">diagnose_if</a></li>
+<li><a class="reference internal" href="#disable-tail-calls-clang-disable-tail-calls" id="id21">disable_tail_calls (clang::disable_tail_calls)</a></li>
+<li><a class="reference internal" href="#enable-if" id="id22">enable_if</a></li>
+<li><a class="reference internal" href="#external-source-symbol-clang-external-source-symbol" id="id23">external_source_symbol (clang::external_source_symbol)</a></li>
+<li><a class="reference internal" href="#flatten-gnu-flatten" id="id24">flatten (gnu::flatten)</a></li>
+<li><a class="reference internal" href="#force-align-arg-pointer-gnu-force-align-arg-pointer" id="id25">force_align_arg_pointer (gnu::force_align_arg_pointer)</a></li>
+<li><a class="reference internal" href="#format-gnu-format" id="id26">format (gnu::format)</a></li>
+<li><a class="reference internal" href="#ifunc-gnu-ifunc" id="id27">ifunc (gnu::ifunc)</a></li>
+<li><a class="reference internal" href="#internal-linkage-clang-internal-linkage" id="id28">internal_linkage (clang::internal_linkage)</a></li>
+<li><a class="reference internal" href="#interrupt-arm" id="id29">interrupt (ARM)</a></li>
+<li><a class="reference internal" href="#interrupt-avr" id="id30">interrupt (AVR)</a></li>
+<li><a class="reference internal" href="#interrupt-mips" id="id31">interrupt (MIPS)</a></li>
+<li><a class="reference internal" href="#kernel" id="id32">kernel</a></li>
+<li><a class="reference internal" href="#long-call-gnu-long-call-gnu-far" id="id33">long_call (gnu::long_call, gnu::far)</a></li>
+<li><a class="reference internal" href="#micromips-gnu-micromips" id="id34">micromips (gnu::micromips)</a></li>
+<li><a class="reference internal" href="#no-caller-saved-registers-gnu-no-caller-saved-registers" id="id35">no_caller_saved_registers (gnu::no_caller_saved_registers)</a></li>
+<li><a class="reference internal" href="#no-sanitize-clang-no-sanitize" id="id36">no_sanitize (clang::no_sanitize)</a></li>
+<li><a class="reference internal" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" id="id37">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a></li>
+<li><a class="reference internal" href="#no-sanitize-memory" id="id38">no_sanitize_memory</a></li>
+<li><a class="reference internal" href="#no-sanitize-thread" id="id39">no_sanitize_thread</a></li>
+<li><a class="reference internal" href="#no-split-stack-gnu-no-split-stack" id="id40">no_split_stack (gnu::no_split_stack)</a></li>
+<li><a class="reference internal" href="#noalias" id="id41">noalias</a></li>
+<li><a class="reference internal" href="#nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result" id="id42">nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result</a></li>
+<li><a class="reference internal" href="#noduplicate-clang-noduplicate" id="id43">noduplicate (clang::noduplicate)</a></li>
+<li><a class="reference internal" href="#nomicromips-gnu-nomicromips" id="id44">nomicromips (gnu::nomicromips)</a></li>
+<li><a class="reference internal" href="#id1" id="id45">noreturn</a></li>
+<li><a class="reference internal" href="#not-tail-called-clang-not-tail-called" id="id46">not_tail_called (clang::not_tail_called)</a></li>
+<li><a class="reference internal" href="#nothrow-gnu-nothrow" id="id47">nothrow (gnu::nothrow)</a></li>
+<li><a class="reference internal" href="#objc-boxable-clang-objc-boxable" id="id48">objc_boxable (clang::objc_boxable)</a></li>
+<li><a class="reference internal" href="#objc-method-family-clang-objc-method-family" id="id49">objc_method_family (clang::objc_method_family)</a></li>
+<li><a class="reference internal" href="#objc-requires-super-clang-objc-requires-super" id="id50">objc_requires_super (clang::objc_requires_super)</a></li>
+<li><a class="reference internal" href="#objc-runtime-name-clang-objc-runtime-name" id="id51">objc_runtime_name (clang::objc_runtime_name)</a></li>
+<li><a class="reference internal" href="#objc-runtime-visible-clang-objc-runtime-visible" id="id52">objc_runtime_visible (clang::objc_runtime_visible)</a></li>
+<li><a class="reference internal" href="#optnone-clang-optnone" id="id53">optnone (clang::optnone)</a></li>
+<li><a class="reference internal" href="#overloadable-clang-overloadable" id="id54">overloadable (clang::overloadable)</a></li>
+<li><a class="reference internal" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" id="id55">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a></li>
+<li><a class="reference internal" href="#short-call-gnu-short-call-gnu-near" id="id56">short_call (gnu::short_call, gnu::near)</a></li>
+<li><a class="reference internal" href="#signal-gnu-signal" id="id57">signal (gnu::signal)</a></li>
+<li><a class="reference internal" href="#target-gnu-target" id="id58">target (gnu::target)</a></li>
+<li><a class="reference internal" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" id="id59">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a></li>
+<li><a class="reference internal" href="#xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument-xray-log-args-clang-xray-log-args" id="id60">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)</a></li>
+<li><a class="reference internal" href="#id2" id="id61">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#variable-attributes" id="id62">Variable Attributes</a><ul>
+<li><a class="reference internal" href="#dllexport-gnu-dllexport" id="id63">dllexport (gnu::dllexport)</a></li>
+<li><a class="reference internal" href="#dllimport-gnu-dllimport" id="id64">dllimport (gnu::dllimport)</a></li>
+<li><a class="reference internal" href="#init-seg" id="id65">init_seg</a></li>
+<li><a class="reference internal" href="#maybe-unused-unused-gnu-unused" id="id66">maybe_unused, unused, gnu::unused</a></li>
+<li><a class="reference internal" href="#nodebug-gnu-nodebug" id="id67">nodebug (gnu::nodebug)</a></li>
+<li><a class="reference internal" href="#noescape-clang-noescape" id="id68">noescape (clang::noescape)</a></li>
+<li><a class="reference internal" href="#nosvm" id="id69">nosvm</a></li>
+<li><a class="reference internal" href="#pass-object-size-clang-pass-object-size" id="id70">pass_object_size (clang::pass_object_size)</a></li>
+<li><a class="reference internal" href="#require-constant-initialization-clang-require-constant-initialization" id="id71">require_constant_initialization (clang::require_constant_initialization)</a></li>
+<li><a class="reference internal" href="#section-gnu-section-declspec-allocate" id="id72">section (gnu::section, __declspec(allocate))</a></li>
+<li><a class="reference internal" href="#swift-context-clang-swift-context" id="id73">swift_context (clang::swift_context)</a></li>
+<li><a class="reference internal" href="#swift-error-result-clang-swift-error-result" id="id74">swift_error_result (clang::swift_error_result)</a></li>
+<li><a class="reference internal" href="#swift-indirect-result-clang-swift-indirect-result" id="id75">swift_indirect_result (clang::swift_indirect_result)</a></li>
+<li><a class="reference internal" href="#swiftcall-clang-swiftcall" id="id76">swiftcall (clang::swiftcall)</a></li>
+<li><a class="reference internal" href="#thread" id="id77">thread</a></li>
+<li><a class="reference internal" href="#tls-model-gnu-tls-model" id="id78">tls_model (gnu::tls_model)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-attributes" id="id79">Type Attributes</a><ul>
+<li><a class="reference internal" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" id="id80">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a></li>
+<li><a class="reference internal" href="#align-value" id="id81">align_value</a></li>
+<li><a class="reference internal" href="#empty-bases" id="id82">empty_bases</a></li>
+<li><a class="reference internal" href="#enum-extensibility-clang-enum-extensibility" id="id83">enum_extensibility (clang::enum_extensibility)</a></li>
+<li><a class="reference internal" href="#flag-enum-clang-flag-enum" id="id84">flag_enum (clang::flag_enum)</a></li>
+<li><a class="reference internal" href="#layout-version" id="id85">layout_version</a></li>
+<li><a class="reference internal" href="#lto-visibility-public-clang-lto-visibility-public" id="id86">lto_visibility_public (clang::lto_visibility_public)</a></li>
+<li><a class="reference internal" href="#novtable" id="id87">novtable</a></li>
+<li><a class="reference internal" href="#objc-subclassing-restricted-clang-objc-subclassing-restricted" id="id88">objc_subclassing_restricted (clang::objc_subclassing_restricted)</a></li>
+<li><a class="reference internal" href="#selectany-gnu-selectany" id="id89">selectany (gnu::selectany)</a></li>
+<li><a class="reference internal" href="#transparent-union-gnu-transparent-union" id="id90">transparent_union (gnu::transparent_union)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#statement-attributes" id="id91">Statement Attributes</a><ul>
+<li><a class="reference internal" href="#pragma-clang-loop" id="id92">#pragma clang loop</a></li>
+<li><a class="reference internal" href="#pragma-unroll-pragma-nounroll" id="id93">#pragma unroll, #pragma nounroll</a></li>
+<li><a class="reference internal" href="#attribute-intel-reqd-sub-group-size" id="id94">__attribute__((intel_reqd_sub_group_size))</a></li>
+<li><a class="reference internal" href="#attribute-opencl-unroll-hint" id="id95">__attribute__((opencl_unroll_hint))</a></li>
+<li><a class="reference internal" href="#read-only-write-only-read-write-read-only-write-only-read-write" id="id96">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a></li>
+<li><a class="reference internal" href="#fallthrough-clang-fallthrough" id="id97">fallthrough, clang::fallthrough</a></li>
+<li><a class="reference internal" href="#suppress-gsl-suppress" id="id98">suppress (gsl::suppress)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id99">Calling Conventions</a><ul>
+<li><a class="reference internal" href="#fastcall-gnu-fastcall-fastcall-fastcall" id="id100">fastcall (gnu::fastcall, __fastcall, _fastcall)</a></li>
+<li><a class="reference internal" href="#ms-abi-gnu-ms-abi" id="id101">ms_abi (gnu::ms_abi)</a></li>
+<li><a class="reference internal" href="#pcs-gnu-pcs" id="id102">pcs (gnu::pcs)</a></li>
+<li><a class="reference internal" href="#preserve-all-clang-preserve-all" id="id103">preserve_all (clang::preserve_all)</a></li>
+<li><a class="reference internal" href="#preserve-most-clang-preserve-most" id="id104">preserve_most (clang::preserve_most)</a></li>
+<li><a class="reference internal" href="#regcall-gnu-regcall-regcall" id="id105">regcall (gnu::regcall, __regcall)</a></li>
+<li><a class="reference internal" href="#regparm-gnu-regparm" id="id106">regparm (gnu::regparm)</a></li>
+<li><a class="reference internal" href="#stdcall-gnu-stdcall-stdcall-stdcall" id="id107">stdcall (gnu::stdcall, __stdcall, _stdcall)</a></li>
+<li><a class="reference internal" href="#thiscall-gnu-thiscall-thiscall-thiscall" id="id108">thiscall (gnu::thiscall, __thiscall, _thiscall)</a></li>
+<li><a class="reference internal" href="#vectorcall-clang-vectorcall-vectorcall-vectorcall" id="id109">vectorcall (clang::vectorcall, __vectorcall, _vectorcall)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#amd-gpu-attributes" id="id110">AMD GPU Attributes</a><ul>
+<li><a class="reference internal" href="#amdgpu-flat-work-group-size-clang-amdgpu-flat-work-group-size" id="id111">amdgpu_flat_work_group_size (clang::amdgpu_flat_work_group_size)</a></li>
+<li><a class="reference internal" href="#amdgpu-num-sgpr-clang-amdgpu-num-sgpr" id="id112">amdgpu_num_sgpr (clang::amdgpu_num_sgpr)</a></li>
+<li><a class="reference internal" href="#amdgpu-num-vgpr-clang-amdgpu-num-vgpr" id="id113">amdgpu_num_vgpr (clang::amdgpu_num_vgpr)</a></li>
+<li><a class="reference internal" href="#amdgpu-waves-per-eu-clang-amdgpu-waves-per-eu" id="id114">amdgpu_waves_per_eu (clang::amdgpu_waves_per_eu)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#consumed-annotation-checking" id="id115">Consumed Annotation Checking</a><ul>
+<li><a class="reference internal" href="#callable-when-clang-callable-when" id="id116">callable_when (clang::callable_when)</a></li>
+<li><a class="reference internal" href="#consumable-clang-consumable" id="id117">consumable (clang::consumable)</a></li>
+<li><a class="reference internal" href="#param-typestate-clang-param-typestate" id="id118">param_typestate (clang::param_typestate)</a></li>
+<li><a class="reference internal" href="#return-typestate-clang-return-typestate" id="id119">return_typestate (clang::return_typestate)</a></li>
+<li><a class="reference internal" href="#set-typestate-clang-set-typestate" id="id120">set_typestate (clang::set_typestate)</a></li>
+<li><a class="reference internal" href="#test-typestate-clang-test-typestate" id="id121">test_typestate (clang::test_typestate)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-safety-checking" id="id122">Type Safety Checking</a><ul>
+<li><a class="reference internal" href="#argument-with-type-tag" id="id123">argument_with_type_tag</a></li>
+<li><a class="reference internal" href="#pointer-with-type-tag" id="id124">pointer_with_type_tag</a></li>
+<li><a class="reference internal" href="#type-tag-for-datatype" id="id125">type_tag_for_datatype</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-address-spaces" id="id126">OpenCL Address Spaces</a><ul>
+<li><a class="reference internal" href="#constant-constant" id="id127">constant (__constant)</a></li>
+<li><a class="reference internal" href="#generic-generic" id="id128">generic (__generic)</a></li>
+<li><a class="reference internal" href="#global-global" id="id129">global (__global)</a></li>
+<li><a class="reference internal" href="#local-local" id="id130">local (__local)</a></li>
+<li><a class="reference internal" href="#private-private" id="id131">private (__private)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nullability-attributes" id="id132">Nullability Attributes</a><ul>
+<li><a class="reference internal" href="#nonnull" id="id133">_Nonnull</a></li>
+<li><a class="reference internal" href="#null-unspecified" id="id134">_Null_unspecified</a></li>
+<li><a class="reference internal" href="#nullable" id="id135">_Nullable</a></li>
+<li><a class="reference internal" href="#nonnull-gnu-nonnull" id="id136">nonnull (gnu::nonnull)</a></li>
+<li><a class="reference internal" href="#returns-nonnull-gnu-returns-nonnull" id="id137">returns_nonnull (gnu::returns_nonnull)</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This page lists the attributes currently supported by Clang.</p>
+</div>
+<div class="section" id="function-attributes">
+<h2><a class="toc-backref" href="#id6">Function Attributes</a><a class="headerlink" href="#function-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="pragma-omp-declare-simd">
+<h3><a class="toc-backref" href="#id7">#pragma omp declare simd</a><a class="headerlink" href="#pragma-omp-declare-simd" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare simd</cite> construct can be applied to a function to enable the creation
+of one or more versions that can process multiple arguments using SIMD
+instructions from a single invocation in a SIMD loop. The <cite>declare simd</cite>
+directive is a declarative directive. There may be multiple <cite>declare simd</cite>
+directives for a function. The use of a <cite>declare simd</cite> construct on a function
+enables the creation of SIMD versions of the associated function that can be
+used to process multiple arguments from a single invocation from a SIMD loop
+concurrently.
+The syntax of the <cite>declare simd</cite> construct is as follows:</p>
+<blockquote>
+<div><div class="highlight-none"><div class="highlight"><pre>#pragma omp declare simd [clause[[,] clause] ...] new-line
+[#pragma omp declare simd [clause[[,] clause] ...] new-line]
+[...]
+function definition or declaration
+</pre></div>
+</div>
+</div></blockquote>
+<p>where clause is one of the following:</p>
+<blockquote>
+<div><div class="highlight-none"><div class="highlight"><pre>simdlen(length)
+linear(argument-list[:constant-linear-step])
+aligned(argument-list[:alignment])
+uniform(argument-list)
+inbranch
+notinbranch
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="pragma-omp-declare-target">
+<h3><a class="toc-backref" href="#id8">#pragma omp declare target</a><a class="headerlink" href="#pragma-omp-declare-target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare target</cite> directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.</p>
+<p>The syntax of the declare target directive is as follows:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma omp declare target new-line</span>
+<span class="n">declarations</span><span class="o">-</span><span class="n">definition</span><span class="o">-</span><span class="n">seq</span>
+<span class="cp">#pragma omp end declare target new-line</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="noreturn">
+<h3><a class="toc-backref" href="#id9">_Noreturn</a><a class="headerlink" href="#noreturn" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="abi-tag-gnu-abi-tag">
+<h3><a class="toc-backref" href="#id10">abi_tag (gnu::abi_tag)</a><a class="headerlink" href="#abi-tag-gnu-abi-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">abi_tag</span></tt> attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+with different ABI versions supported. For example, a newer version of a class
+could have a different set of data members and thus have a different size. Using
+the <tt class="docutils literal"><span class="pre">abi_tag</span></tt> attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefor, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.</p>
+</div>
+<div class="section" id="acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id11">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a><a class="headerlink" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as acquiring a capability.</p>
+</div>
+<div class="section" id="alloc-align-gnu-alloc-align">
+<h3><a class="toc-backref" href="#id12">alloc_align (gnu::alloc_align)</a><a class="headerlink" href="#alloc-align-gnu-alloc-align" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((alloc_align(<alignment>))</span></tt> on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter. The
+parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit <tt class="docutils literal"><span class="pre">this</span></tt>
+parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The returned pointer has the alignment specified by the first parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">a</span><span class="p">(</span><span class="n">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">1</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer has the alignment specified by the second parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">b</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">v</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">2</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer has the alignment specified by the second visible</span>
+<span class="c1">// parameter, however it must be adjusted for the implicit 'this' parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">Foo</span><span class="o">::</span><span class="n">b</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">v</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">3</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Note that this attribute merely informs the compiler that a function always
+returns a sufficiently aligned pointer. It does not cause the compiler to
+emit code to enforce that alignment. The behavior is undefined if the returned
+poitner is not sufficiently aligned.</p>
+</div>
+<div class="section" id="alloc-size-gnu-alloc-size">
+<h3><a class="toc-backref" href="#id13">alloc_size (gnu::alloc_size)</a><a class="headerlink" href="#alloc-size-gnu-alloc-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">alloc_size</span></tt> attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned poiner. <tt class="docutils literal"><span class="pre">alloc_size</span></tt> takes one or two arguments.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">alloc_size(N)</span></tt> implies that argument number N equals the number of
+available bytes at the returned pointer.</li>
+<li><tt class="docutils literal"><span class="pre">alloc_size(N,</span> <span class="pre">M)</span></tt> implies that the product of argument number N and
+argument number M equals the number of available bytes at the returned
+pointer.</li>
+</ul>
+<p>Argument numbers are 1-based.</p>
+<p>An example of how to use <tt class="docutils literal"><span class="pre">alloc_size</span></tt></p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">my_malloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">my_calloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="o">=</span> <span class="n">my_malloc</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">a</span> <span class="o">=</span> <span class="n">my_calloc</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">5</span><span class="p">);</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This attribute works differently in clang than it does in GCC.
+Specifically, clang will only trace <tt class="docutils literal"><span class="pre">const</span></tt> pointers (as above); we give up
+on pointers that are not marked as <tt class="docutils literal"><span class="pre">const</span></tt>. In the vast majority of cases,
+this is unimportant, because LLVM has support for the <tt class="docutils literal"><span class="pre">alloc_size</span></tt>
+attribute. However, this may cause mildly unintuitive behavior when used with
+other attributes, such as <tt class="docutils literal"><span class="pre">enable_if</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability">
+<h3><a class="toc-backref" href="#id14">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a><a class="headerlink" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.</p>
+</div>
+<div class="section" id="assume-aligned-gnu-assume-aligned">
+<h3><a class="toc-backref" href="#id15">assume_aligned (gnu::assume_aligned)</a><a class="headerlink" href="#assume-aligned-gnu-assume-aligned" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((assume_aligned(<alignment>[,<offset>]))</span></tt> on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The returned pointer value has 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">a</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer value is 4 bytes greater than an address having</span>
+<span class="c1">// 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">b</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">,</span> <span class="mi">4</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.</p>
+</div>
+<div class="section" id="availability">
+<h3><a class="toc-backref" href="#id16">availability</a><a class="headerlink" href="#availability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">availability</span></tt> attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function <tt class="docutils literal"><span class="pre">f</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">,</span><span class="n">deprecated</span><span class="o">=</span><span class="mf">10.6</span><span class="p">,</span><span class="n">obsoleted</span><span class="o">=</span><span class="mf">10.7</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>The availability attribute states that <tt class="docutils literal"><span class="pre">f</span></tt> was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
+is used by Clang to determine when it is safe to use <tt class="docutils literal"><span class="pre">f</span></tt>: for example, if
+Clang is instructed to compile code for macOS 10.5, a call to <tt class="docutils literal"><span class="pre">f()</span></tt>
+succeeds. If Clang is instructed to compile code for macOS 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for macOS 10.7, the call
+fails because <tt class="docutils literal"><span class="pre">f()</span></tt> is no longer available.</p>
+<p>The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration’s lifetime (in any order) along with additional information. Those
+clauses can be:</p>
+<dl class="docutils">
+<dt>introduced=<em>version</em></dt>
+<dd>The first version in which this declaration was introduced.</dd>
+<dt>deprecated=<em>version</em></dt>
+<dd>The first version in which this declaration was deprecated, meaning that
+users should migrate away from this API.</dd>
+<dt>obsoleted=<em>version</em></dt>
+<dd>The first version in which this declaration was obsoleted, meaning that it
+was removed completely and can no longer be used.</dd>
+<dt>unavailable</dt>
+<dd>This declaration is never available on this platform.</dd>
+<dt>message=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will provide when emitting a warning or
+error about use of a deprecated or obsoleted declaration. Useful to direct
+users to replacement APIs.</dd>
+<dt>replacement=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will use to provide Fix-It when emitting
+a warning about use of a deprecated declaration. The Fix-It will replace
+the deprecated declaration with the new declaration specified.</dd>
+</dl>
+<p>Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored. If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored. Supported platforms
+are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ios</span></tt></dt>
+<dd>Apple’s iOS operating system. The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mios-version-min=*version*</span></tt> or <tt class="docutils literal"><span class="pre">-miphoneos-version-min=*version*</span></tt>
+command-line arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">macos</span></tt></dt>
+<dd>Apple’s macOS operating system. The minimum deployment target is
+specified by the <tt class="docutils literal"><span class="pre">-mmacosx-version-min=*version*</span></tt> command-line argument.
+<tt class="docutils literal"><span class="pre">macosx</span></tt> is supported for backward-compatibility reasons, but it is
+deprecated.</dd>
+<dt><tt class="docutils literal"><span class="pre">tvos</span></tt></dt>
+<dd>Apple’s tvOS operating system. The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mtvos-version-min=*version*</span></tt> command-line argument.</dd>
+<dt><tt class="docutils literal"><span class="pre">watchos</span></tt></dt>
+<dd>Apple’s watchOS operating system. The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mwatchos-version-min=*version*</span></tt> command-line argument.</dd>
+</dl>
+<p>A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced. When this happens, the
+declaration is <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly linked</a>,
+as if the <tt class="docutils literal"><span class="pre">weak_import</span></tt> attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.</p>
+<p>The flag <tt class="docutils literal"><span class="pre">strict</span></tt> disallows using API when deploying back to a
+platform version prior to when the declaration was introduced. An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.</p>
+<p>If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span> <span class="c1">// okay, matches</span>
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">ios</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">4.0</span><span class="p">)));</span> <span class="c1">// okay, adds a new platform</span>
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> <span class="c1">// okay, inherits both macos and ios availability from above.</span>
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: mismatch</span>
+</pre></div>
+</div>
+<p>When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">A</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">method2</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">@end</span>
+
+<span class="k">@interface</span> <span class="nc">B</span> : <span class="nc">A</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.3</span><span class="p">)));</span> <span class="c1">// okay: method moved into base class later</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: this method was available via the base class in 10.4</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Starting with the macOS 10.12 SDK, the <tt class="docutils literal"><span class="pre">API_AVAILABLE</span></tt> macro from
+<tt class="docutils literal"><span class="pre"><os/availability.h></span></tt> can simplify the spelling:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">A</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">method</span> <span class="n">API_AVAILABLE</span><span class="p">(</span><span class="n">macos</span><span class="p">(</span><span class="mf">10.11</span><span class="p">)));</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">otherMethod</span> <span class="n">API_AVAILABLE</span><span class="p">(</span><span class="n">macos</span><span class="p">(</span><span class="mf">10.11</span><span class="p">),</span> <span class="n">ios</span><span class="p">(</span><span class="mf">11.0</span><span class="p">));</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Also see the documentation for <a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available">@available</a></p>
+</div>
+<div class="section" id="carries-dependency">
+<h3><a class="toc-backref" href="#id17">carries_dependency</a><a class="headerlink" href="#carries-dependency" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">carries_dependency</span></tt> attribute specifies dependency propagation into and
+out of functions.</p>
+<p>When specified on a function or Objective-C method, the <tt class="docutils literal"><span class="pre">carries_dependency</span></tt>
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.</p>
+<p>Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.</p>
+</div>
+<div class="section" id="convergent-clang-convergent">
+<h3><a class="toc-backref" href="#id18">convergent (clang::convergent)</a><a class="headerlink" href="#convergent-clang-convergent" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">convergent</span></tt> attribute can be placed on a function declaration. It is
+translated into the LLVM <tt class="docutils literal"><span class="pre">convergent</span></tt> attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.</p>
+<p>In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.</p>
+<p>This attribute is different from <tt class="docutils literal"><span class="pre">noduplicate</span></tt> because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.</p>
+<p>Sample usage:
+.. code-block:: c</p>
+<blockquote>
+<div>void convfunc(void) __attribute__((convergent));
+// Setting it as a C++11 attribute is also valid in a C++ program.
+// void convfunc(void) [[clang::convergent]];</div></blockquote>
+</div>
+<div class="section" id="deprecated-gnu-deprecated">
+<h3><a class="toc-backref" href="#id19">deprecated (gnu::deprecated)</a><a class="headerlink" href="#deprecated-gnu-deprecated" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">deprecated</span></tt> attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.</p>
+<p>Consider the function declaration for a hypothetical function <tt class="docutils literal"><span class="pre">f</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">(</span><span class="s">"message"</span><span class="p">,</span> <span class="s">"replacement"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>When spelled as <cite>__attribute__((deprecated))</cite>, the deprecated attribute can have
+two optional string arguments. The first one is the message to display when
+emitting the warning; the second one enables the compiler to provide a Fix-It
+to replace the deprecated name with a new name. Otherwise, when spelled as
+<cite>[[gnu::deprecated]] or [[deprecated]]</cite>, the attribute can have one optional
+string argument which is the message to display when emitting the warning.</p>
+</div>
+<div class="section" id="diagnose-if">
+<h3><a class="toc-backref" href="#id20">diagnose_if</a><a class="headerlink" href="#diagnose-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="n">abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="n">must_abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">val</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// warning: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val2</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// error: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val3</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">val4</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span> <span class="c1">// Because run-time checks are not emitted for</span>
+ <span class="c1">// diagnose_if attributes, this executes without</span>
+ <span class="c1">// issue.</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">diagnose_if</span></tt> is closely related to <tt class="docutils literal"><span class="pre">enable_if</span></tt>, with a few key differences:</p>
+<ul class="simple">
+<li>Overload resolution is not aware of <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes: they’re
+considered only after we select the best candidate from a given candidate set.</li>
+<li>Function declarations that differ only in their <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes are
+considered to be redeclarations of the same function (not overloads).</li>
+<li>If the condition provided to <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> cannot be evaluated, no
+diagnostic will be emitted.</li>
+</ul>
+<p>Otherwise, <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> is essentially the logical negation of <tt class="docutils literal"><span class="pre">enable_if</span></tt>.</p>
+<p>As a result of bullet number two, <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes will stack on the
+same function. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag1"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag2"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">bar</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span> <span class="c1">// warning: diag1</span>
+ <span class="c1">// warning: diag2</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fooptr</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span> <span class="c1">// warning: diag1</span>
+ <span class="c1">// warning: diag2</span>
+
+<span class="n">constexpr</span> <span class="kt">int</span> <span class="nf">supportsAPILevel</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">N</span> <span class="o"><</span> <span class="mi">5</span><span class="p">;</span> <span class="p">}</span>
+<span class="kt">int</span> <span class="n">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">supportsAPILevel</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span>
+ <span class="s">"Upgrade to API level 10 to use baz"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">a</span><span class="p">,</span> <span class="s">"0 is not recommended."</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">bazptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="n">baz</span><span class="p">;</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+<span class="kt">int</span> <span class="n">v</span> <span class="o">=</span> <span class="n">baz</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+</pre></div>
+</div>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(diagnose_if)</span></tt>.</p>
+</div>
+<div class="section" id="disable-tail-calls-clang-disable-tail-calls">
+<h3><a class="toc-backref" href="#id21">disable_tail_calls (clang::disable_tail_calls)</a><a class="headerlink" href="#disable-tail-calls-clang-disable-tail-calls" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">disable_tail_calls</span></tt> attribute instructs the backend to not perform tail call optimization inside the marked function.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">disable_tail_calls</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">callee</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// This call is not tail-call optimized.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <tt class="docutils literal"><span class="pre">disable_tail_calls</span></tt> is legal.</p>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">disable_tail_calls</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is not tail-call optimized.</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is tail-call optimized.</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="enable-if">
+<h3><a class="toc-backref" href="#id22">enable_if</a><a class="headerlink" href="#enable-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some features of this attribute are experimental. The meaning of
+multiple enable_if attributes on a single declaration is subject to change in
+a future version of clang. Also, the ABI is not standardized and the name
+mangling may change in future versions. To avoid that, use asm labels.</p>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">enable_if</span></tt> attribute can be placed on function declarations to control
+which overload is selected based on the values of the function’s arguments.
+When combined with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, this feature is also
+available in C.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">c</span> <span class="o"><=</span> <span class="o">-</span><span class="mi">1</span> <span class="o">||</span> <span class="n">c</span> <span class="o">></span> <span class="mi">255</span><span class="p">,</span> <span class="s">"chosen when 'c' is out of range"</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">unavailable</span><span class="p">(</span><span class="s">"'c' must have the value of an unsigned char or EOF"</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="kt">char</span> <span class="n">c</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">);</span> <span class="c1">// results in a compile-time error.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.</p>
+<p>The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.</p>
+<p>Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">always_inline</span><span class="p">))</span>
+<span class="k">static</span> <span class="kr">inline</span> <span class="n">size_t</span> <span class="n">strnlen</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">maxlen</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="o">-</span><span class="mi">1</span><span class="p">))),</span>
+ <span class="s">"chosen when the buffer size is known but 'maxlen' is not"</span><span class="p">)))</span>
+<span class="p">{</span>
+ <span class="k">return</span> <span class="n">strnlen_chk</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">,</span> <span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="kc">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="n">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="kc">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="kc">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #2</span>
+
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="n">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">j</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="kc">true</span><span class="p">)));</span> <span class="c1">// #2</span>
+</pre></div>
+</div>
+<p>In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(enable_if)</span></tt>.</p>
+<p>Note that functions with one or more <tt class="docutils literal"><span class="pre">enable_if</span></tt> attributes may not have
+their address taken, unless all of the conditions specified by said
+<tt class="docutils literal"><span class="pre">enable_if</span></tt> are constants that evaluate to <tt class="docutils literal"><span class="pre">true</span></tt>. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">const</span> <span class="kt">int</span> <span class="n">TrueConstant</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="k">const</span> <span class="kt">int</span> <span class="n">FalseConstant</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">a</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">h</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">i</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">TrueConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="n">j</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">FalseConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">fn</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">ptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">);</span>
+ <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">f</span><span class="p">;</span> <span class="c1">// error: 'a > 0' is not always true</span>
+ <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">g</span><span class="p">;</span> <span class="c1">// error: 'a == 0 || a != 0' is not a truthy constant</span>
+ <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">h</span><span class="p">;</span> <span class="c1">// OK: 1 is a truthy constant</span>
+ <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">i</span><span class="p">;</span> <span class="c1">// OK: 'TrueConstant' is a truthy constant</span>
+ <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">j</span><span class="p">;</span> <span class="c1">// error: 'FalseConstant' is a constant, but not truthy</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Because <tt class="docutils literal"><span class="pre">enable_if</span></tt> evaluation happens during overload resolution,
+<tt class="docutils literal"><span class="pre">enable_if</span></tt> may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for <tt class="docutils literal"><span class="pre">foo</span></tt> in <tt class="docutils literal"><span class="pre">bar</span></tt>, but not in <tt class="docutils literal"><span class="pre">baz</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">double</span> <span class="n">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o"><=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">I</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">I</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">baz</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span><span class="o">::</span><span class="n">number</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">struct</span> <span class="n">WithNumber</span> <span class="p">{</span> <span class="n">constexpr</span> <span class="k">static</span> <span class="kt">int</span> <span class="n">number</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="p">};</span>
+<span class="kt">void</span> <span class="n">callThem</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="o"><</span><span class="k">sizeof</span><span class="p">(</span><span class="n">WithNumber</span><span class="p">)</span><span class="o">></span><span class="p">();</span>
+ <span class="n">baz</span><span class="o"><</span><span class="n">WithNumber</span><span class="o">></span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is because, in <tt class="docutils literal"><span class="pre">bar</span></tt>, <tt class="docutils literal"><span class="pre">foo</span></tt> is resolved prior to template
+instantiation, so the value for <tt class="docutils literal"><span class="pre">I</span></tt> isn’t known (thus, both <tt class="docutils literal"><span class="pre">enable_if</span></tt>
+conditions for <tt class="docutils literal"><span class="pre">foo</span></tt> fail). However, in <tt class="docutils literal"><span class="pre">baz</span></tt>, <tt class="docutils literal"><span class="pre">foo</span></tt> is resolved during
+template instantiation, so the value for <tt class="docutils literal"><span class="pre">T::number</span></tt> is known.</p>
+</div>
+<div class="section" id="external-source-symbol-clang-external-source-symbol">
+<h3><a class="toc-backref" href="#id23">external_source_symbol (clang::external_source_symbol)</a><a class="headerlink" href="#external-source-symbol-clang-external-source-symbol" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">external_source_symbol</span></tt> attribute specifies that a declaration originates
+from an external source and describes the nature of that source.</p>
+<p>The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct ‘jump-to-definition’ feature. For a concrete example,
+consider a protocol that’s defined in a Swift file:</p>
+<div class="highlight-swift"><pre>@objc public protocol SwiftProtocol {
+ func method()
+}</pre>
+</div>
+<p>This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the <tt class="docutils literal"><span class="pre">external_source_symbol</span></tt> attribute to make Clang aware of the fact
+that <tt class="docutils literal"><span class="pre">SwiftProtocol</span></tt> actually originates from a Swift module:</p>
+<div class="highlight-objc"><pre>__attribute__((external_source_symbol(language="Swift",defined_in="module")))
+ at protocol SwiftProtocol
+ at required
+- (void) method;
+ at end</pre>
+</div>
+<p>Consequently, when ‘jump-to-definition’ is performed at a location that
+references <tt class="docutils literal"><span class="pre">SwiftProtocol</span></tt>, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.</p>
+<p>The <tt class="docutils literal"><span class="pre">external_source_symbol</span></tt> attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:</p>
+<dl class="docutils">
+<dt>language=<em>string-literal</em></dt>
+<dd>The name of the source language in which this declaration was defined.</dd>
+<dt>defined_in=<em>string-literal</em></dt>
+<dd>The name of the source container in which the declaration was defined. The
+exact definition of source container is language-specific, e.g. Swift’s
+source containers are modules, so <tt class="docutils literal"><span class="pre">defined_in</span></tt> should specify the Swift
+module name.</dd>
+<dt>generated_declaration</dt>
+<dd>This declaration was automatically generated by some tool.</dd>
+</dl>
+<p>The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.</p>
+</div>
+<div class="section" id="flatten-gnu-flatten">
+<h3><a class="toc-backref" href="#id24">flatten (gnu::flatten)</a><a class="headerlink" href="#flatten-gnu-flatten" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">flatten</span></tt> attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the <tt class="docutils literal"><span class="pre">noinline</span></tt> attribute.</p>
+</div>
+<div class="section" id="force-align-arg-pointer-gnu-force-align-arg-pointer">
+<h3><a class="toc-backref" href="#id25">force_align_arg_pointer (gnu::force_align_arg_pointer)</a><a class="headerlink" href="#force-align-arg-pointer-gnu-force-align-arg-pointer" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use this attribute to force stack alignment.</p>
+<p>Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like ‘movaps’) that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.</p>
+<p>Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, ‘force_align_arg_pointer’ is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span> <span class="p">((</span><span class="n">force_align_arg_pointer</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">()</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="format-gnu-format">
+<h3><a class="toc-backref" href="#id26">format (gnu::format)</a><a class="headerlink" href="#format-gnu-format" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">format</span></tt> attribute, which indicates that the function
+accepts a <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">scanf</span></tt>-like format string and corresponding
+arguments or a <tt class="docutils literal"><span class="pre">va_list</span></tt> that contains these arguments.</p>
+<p>Please see <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC documentation about format attribute</a> to find details
+about attribute syntax.</p>
+<p>Clang implements two kinds of checks with this attribute.</p>
+<ol class="arabic">
+<li><p class="first">Clang checks that the function with the <tt class="docutils literal"><span class="pre">format</span></tt> attribute is called with
+a format string that uses format specifiers that are allowed, and that
+arguments match the format string. This is the <tt class="docutils literal"><span class="pre">-Wformat</span></tt> warning, it is
+on by default.</p>
+</li>
+<li><p class="first">Clang checks that the format string argument is a literal string. This is
+the <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning, it is off by default.</p>
+<p>Clang implements this mostly the same way as GCC, but there is a difference
+for functions that accept a <tt class="docutils literal"><span class="pre">va_list</span></tt> argument (for example, <tt class="docutils literal"><span class="pre">vprintf</span></tt>).
+GCC does not emit <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning for calls to such
+functions. Clang does not warn if the format string comes from a function
+parameter, where the function is annotated with a compatible attribute,
+otherwise it warns. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__scanf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+ <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+ <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+ <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning: format string is not a string literal</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case we warn because <tt class="docutils literal"><span class="pre">s</span></tt> contains a format string for a
+<tt class="docutils literal"><span class="pre">scanf</span></tt>-like function, but it is passed to a <tt class="docutils literal"><span class="pre">printf</span></tt>-like function.</p>
+<p>If the attribute is removed, clang still warns, because the format string is
+not a string literal.</p>
+<p>Another example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__printf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+ <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+ <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+ <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case Clang does not warn because the format string <tt class="docutils literal"><span class="pre">s</span></tt> and
+the corresponding arguments are annotated. If the arguments are
+incorrect, the caller of <tt class="docutils literal"><span class="pre">foo</span></tt> will receive a warning.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="ifunc-gnu-ifunc">
+<h3><a class="toc-backref" href="#id27">ifunc (gnu::ifunc)</a><a class="headerlink" href="#ifunc-gnu-ifunc" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((ifunc("resolver")))</span></tt> is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.</p>
+<p>The symbol name of the resolver function is given in quotes. A function with this name (after mangling) must be defined in the current translation unit; it may be <tt class="docutils literal"><span class="pre">static</span></tt>. The resolver function should take no arguments and return a pointer.</p>
+<p>The <tt class="docutils literal"><span class="pre">ifunc</span></tt> attribute may only be used on a function declaration. A function declaration with an <tt class="docutils literal"><span class="pre">ifunc</span></tt> attribute is considered to be a definition of the declared entity. The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.</p>
+<p>Not all targets support this attribute. ELF targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher. Non-ELF targets currently do not support this attribute.</p>
+</div>
+<div class="section" id="internal-linkage-clang-internal-linkage">
+<h3><a class="toc-backref" href="#id28">internal_linkage (clang::internal_linkage)</a><a class="headerlink" href="#internal-linkage-clang-internal-linkage" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">internal_linkage</span></tt> attribute changes the linkage type of the declaration to internal.
+This is similar to C-style <tt class="docutils literal"><span class="pre">static</span></tt>, but can be used on classes and class methods. When applied to a class definition,
+this attribute affects all methods and static data members of that class.
+This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.</p>
+</div>
+<div class="section" id="interrupt-arm">
+<h3><a class="toc-backref" href="#id29">interrupt (ARM)</a><a class="headerlink" href="#interrupt-arm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt("TYPE")))</span></tt> attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.</p>
+<p>The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: “IRQ”,
+“FIQ”, “SWI”, “ABORT”, “UNDEF”.</p>
+<p>The semantics are as follows:</p>
+<ul>
+<li><p class="first">If the function is AAPCS, Clang instructs the backend to realign the stack to
+8 bytes on entry. This is a general requirement of the AAPCS at public
+interfaces, but may not hold when an exception is taken. Doing this allows
+other AAPCS functions to be called.</p>
+</li>
+<li><p class="first">If the CPU is M-class this is all that needs to be done since the architecture
+itself is designed in such a way that functions obeying the normal AAPCS ABI
+constraints are valid exception handlers.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the prologue and epilogue are modified to save all
+non-banked registers that are used, so that upon return the user-mode state
+will not be corrupted. Note that to avoid unnecessary overhead, only
+general-purpose (integer) registers are saved in this way. If VFP operations
+are needed, that state must be saved manually.</p>
+<p>Specifically, interrupt kinds other than “FIQ” will save all core registers
+except “lr” and “sp”. “FIQ” interrupts will save r0-r7.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the return instruction is changed to one of the
+canonical sequences permitted by the architecture for exception return. Where
+possible the function itself will make the necessary “lr” adjustments so that
+the “preferred return address” is selected.</p>
+<p>Unfortunately the compiler is unable to make this guarantee for an “UNDEF”
+handler, where the offset from “lr” to the preferred return address depends on
+the execution state of the code which generated the exception. In this case
+a sequence equivalent to “movs pc, lr” will be used.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="interrupt-avr">
+<h3><a class="toc-backref" href="#id30">interrupt (AVR)</a><a class="headerlink" href="#interrupt-avr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt))</span></tt> attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.</p>
+</div>
+<div class="section" id="interrupt-mips">
+<h3><a class="toc-backref" href="#id31">interrupt (MIPS)</a><a class="headerlink" href="#interrupt-mips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt("ARGUMENT")))</span></tt> attribute on
+MIPS targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>By default, the compiler will produce a function prologue and epilogue suitable for
+an interrupt service routine that handles an External Interrupt Controller (eic)
+generated interrupt. This behaviour can be explicitly requested with the “eic”
+argument.</p>
+<p>Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form “vector=LEVEL” where LEVEL is one of the following values:
+“sw0”, “sw1”, “hw0”, “hw1”, “hw2”, “hw3”, “hw4”, “hw5”. The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.</p>
+<p>The semantics are as follows:</p>
+<ul class="simple">
+<li>The prologue is modified so that the Exception Program Counter (EPC) and
+Status coprocessor registers are saved to the stack. The interrupt mask is
+set so that the function can only be interrupted by a higher priority
+interrupt. The epilogue will restore the previous values of EPC and Status.</li>
+<li>The prologue and epilogue are modified to save and restore all non-kernel
+registers as necessary.</li>
+<li>The FPU is disabled in the prologue, as the floating pointer registers are not
+spilled to the stack.</li>
+<li>The function return sequence is changed to use an exception return instruction.</li>
+<li>The parameter sets the interrupt mask for the function corresponding to the
+interrupt level specified. If no mask is specified the interrupt mask
+defaults to “eic”.</li>
+</ul>
+</div>
+<div class="section" id="kernel">
+<h3><a class="toc-backref" href="#id32">kernel</a><a class="headerlink" href="#kernel" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((kernel))</span></tt> is used to mark a <tt class="docutils literal"><span class="pre">kernel</span></tt> function in
+RenderScript.</p>
+<p>In RenderScript, <tt class="docutils literal"><span class="pre">kernel</span></tt> functions are used to express data-parallel
+computations. The RenderScript runtime efficiently parallelizes <tt class="docutils literal"><span class="pre">kernel</span></tt>
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the <a class="reference external" href="https://developer.android.com/guide/topics/renderscript/compute.html">RenderScript</a> documentation for more information.</p>
+</div>
+<div class="section" id="long-call-gnu-long-call-gnu-far">
+<h3><a class="toc-backref" href="#id33">long_call (gnu::long_call, gnu::far)</a><a class="headerlink" href="#long-call-gnu-long-call-gnu-far" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((long_call))</span></tt>, <tt class="docutils literal"><span class="pre">__attribute__((far))</span></tt>,
+and <tt class="docutils literal"><span class="pre">__attribute__((near))</span></tt> attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The <tt class="docutils literal"><span class="pre">near</span></tt> attribute
+allows calls to the function to be made using the <tt class="docutils literal"><span class="pre">jal</span></tt> instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller. The <tt class="docutils literal"><span class="pre">long_call</span></tt> and <tt class="docutils literal"><span class="pre">far</span></tt> attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.</p>
+<p>These attributes have no effect for position-independent code.</p>
+<p>These attributes take priority over command line switches such
+as <tt class="docutils literal"><span class="pre">-mlong-calls</span></tt> and <tt class="docutils literal"><span class="pre">-mno-long-calls</span></tt>.</p>
+</div>
+<div class="section" id="micromips-gnu-micromips">
+<h3><a class="toc-backref" href="#id34">micromips (gnu::micromips)</a><a class="headerlink" href="#micromips-gnu-micromips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((micromips))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((nomicromips))</span></tt> attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.</p>
+<p>These attributes override the <cite>-mmicromips</cite> and <cite>-mno-micromips</cite> options
+on the command line.</p>
+</div>
+<div class="section" id="no-caller-saved-registers-gnu-no-caller-saved-registers">
+<h3><a class="toc-backref" href="#id35">no_caller_saved_registers (gnu::no_caller_saved_registers)</a><a class="headerlink" href="#no-caller-saved-registers-gnu-no-caller-saved-registers" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.</p>
+<p>The user can call functions specified with the ‘no_caller_saved_registers’
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.</p>
+<p>Note that ‘no_caller_saved_registers’ attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span> <span class="p">((</span><span class="n">no_caller_saved_registers</span><span class="p">,</span> <span class="n">fastcall</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">(</span><span class="kt">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">arg2</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case parameters ‘arg1’ and ‘arg2’ will be passed in registers.
+In this case, on 32-bit x86 targets, the function ‘f’ will use ECX and EDX as
+register parameters. However, it will not assume any scratch registers and
+should save and restore any modified registers except for ECX and EDX.</p>
+</div></blockquote>
+</div>
+<div class="section" id="no-sanitize-clang-no-sanitize">
+<h3><a class="toc-backref" href="#id36">no_sanitize (clang::no_sanitize)</a><a class="headerlink" href="#no-sanitize-clang-no-sanitize" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Use the <tt class="docutils literal"><span class="pre">no_sanitize</span></tt> attribute on a function declaration to specify
+that a particular instrumentation or set of instrumentations should not be
+applied to that function. The attribute takes a list of string literals,
+which have the same meaning as values accepted by the <tt class="docutils literal"><span class="pre">-fno-sanitize=</span></tt>
+flag. For example, <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("address",</span> <span class="pre">"thread")))</span></tt>
+specifies that AddressSanitizer and ThreadSanitizer should not be applied
+to the function.</p>
+<p>See <a class="reference internal" href="UsersManual.html#controlling-code-generation"><em>Controlling Code Generation</em></a> for a
+full list of supported sanitizer flags.</p>
+</div>
+<div class="section" id="no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address">
+<h3><a class="toc-backref" href="#id37">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a><a class="headerlink" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-address-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt> on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.</p>
+</div>
+<div class="section" id="no-sanitize-memory">
+<h3><a class="toc-backref" href="#id38">no_sanitize_memory</a><a class="headerlink" href="#no-sanitize-memory" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-memory-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_memory))</span></tt> on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.</p>
+</div>
+<div class="section" id="no-sanitize-thread">
+<h3><a class="toc-backref" href="#id39">no_sanitize_thread</a><a class="headerlink" href="#no-sanitize-thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-thread-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_thread))</span></tt> on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.</p>
+</div>
+<div class="section" id="no-split-stack-gnu-no-split-stack">
+<h3><a class="toc-backref" href="#id40">no_split_stack (gnu::no_split_stack)</a><a class="headerlink" href="#no-split-stack-gnu-no-split-stack" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">no_split_stack</span></tt> attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if <tt class="docutils literal"><span class="pre">-fsplit-stack</span></tt>
+is not specified.</p>
+</div>
+<div class="section" id="noalias">
+<h3><a class="toc-backref" href="#id41">noalias</a><a class="headerlink" href="#noalias" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">noalias</span></tt> attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.</p>
+</div>
+<div class="section" id="nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result">
+<h3><a class="toc-backref" href="#id42">nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result</a><a class="headerlink" href="#nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the ability to diagnose when the results of a function call
+expression are discarded under suspicious circumstances. A diagnostic is
+generated when a function or its return type is marked with <tt class="docutils literal"><span class="pre">[[nodiscard]]</span></tt>
+(or <tt class="docutils literal"><span class="pre">__attribute__((warn_unused_result))</span></tt>) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+<cite>void</cite>.</p>
+</div>
+<div class="section" id="noduplicate-clang-noduplicate">
+<h3><a class="toc-backref" href="#id43">noduplicate (clang::noduplicate)</a><a class="headerlink" href="#noduplicate-clang-noduplicate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">noduplicate</span></tt> attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL “barrier” function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+“nodupfunc” in the code below avoids that:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="n">nodupfunc</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">noduplicate</span><span class="p">));</span>
+<span class="c1">// Setting it as a C++11 attribute is also valid</span>
+<span class="c1">// void nodupfunc() [[clang::noduplicate]];</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+<span class="kt">void</span> <span class="n">bar</span><span class="p">();</span>
+
+<span class="n">nodupfunc</span><span class="p">();</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>gets possibly modified by some optimizations into code similar to this:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">nodupfunc</span><span class="p">();</span>
+ <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">nodupfunc</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>where the call to “nodupfunc” is duplicated and sunk into the two branches
+of the condition.</p>
+</div>
+<div class="section" id="nomicromips-gnu-nomicromips">
+<h3><a class="toc-backref" href="#id44">nomicromips (gnu::nomicromips)</a><a class="headerlink" href="#nomicromips-gnu-nomicromips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((micromips))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((nomicromips))</span></tt> attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.</p>
+<p>These attributes override the <cite>-mmicromips</cite> and <cite>-mno-micromips</cite> options
+on the command line.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id45">noreturn</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="not-tail-called-clang-not-tail-called">
+<h3><a class="toc-backref" href="#id46">not_tail_called (clang::not_tail_called)</a><a class="headerlink" href="#not-tail-called-clang-not-tail-called" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">not_tail_called</span></tt> attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as <tt class="docutils literal"><span class="pre">always_inline</span></tt> cannot be marked as <tt class="docutils literal"><span class="pre">not_tail_called</span></tt>.</p>
+<p>For example, it prevents tail-call optimization in the following case:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">foo1</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// No tail-call optimization on direct calls.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>However, it doesn’t prevent tail-call optimization in this case:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo1</span><span class="p">;</span>
+
+ <span class="c1">// not_tail_called has no effect on an indirect call even if the call can be</span>
+ <span class="c1">// resolved at compile time.</span>
+ <span class="k">return</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <tt class="docutils literal"><span class="pre">not_tail_called</span></tt> is an error:</p>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">// not_tail_called on a virtual function is an error.</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">();</span>
+
+ <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo2</span><span class="p">();</span>
+
+ <span class="c1">// Non-virtual functions can be marked ``not_tail_called``.</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo3</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="n">override</span><span class="p">;</span>
+
+ <span class="c1">// not_tail_called on a virtual function is an error.</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo2</span><span class="p">()</span> <span class="n">override</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="nothrow-gnu-nothrow">
+<h3><a class="toc-backref" href="#id47">nothrow (gnu::nothrow)</a><a class="headerlink" href="#nothrow-gnu-nothrow" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((nothrow))</span></tt> and Microsoft style
+<tt class="docutils literal"><span class="pre">__declspec(nothrow)</span></tt> attribute as an equivilent of <cite>noexcept</cite> on function
+declarations. This attribute informs the compiler that the annotated function
+does not throw an exception. This prevents exception-unwinding. This attribute
+is particularly useful on functions in the C Standard Library that are
+guaranteed to not throw an exception.</p>
+</div>
+<div class="section" id="objc-boxable-clang-objc-boxable">
+<h3><a class="toc-backref" href="#id48">objc_boxable (clang::objc_boxable)</a><a class="headerlink" href="#objc-boxable-clang-objc-boxable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Structs and unions marked with the <tt class="docutils literal"><span class="pre">objc_boxable</span></tt> attribute can be used
+with the Objective-C boxed expression syntax, <tt class="docutils literal"><span class="pre">@(...)</span></tt>.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_boxable))</span></tt>. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:</p>
+<div class="highlight-objc"><pre>struct __attribute__((objc_boxable)) some_struct {
+ int i;
+};
+union __attribute__((objc_boxable)) some_union {
+ int i;
+ float f;
+};
+typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
+
+// ...
+
+some_struct ss;
+NSValue *boxed = @(ss);</pre>
+</div>
+</div>
+<div class="section" id="objc-method-family-clang-objc-method-family">
+<h3><a class="toc-backref" href="#id49">objc_method_family (clang::objc_method_family)</a><a class="headerlink" href="#objc-method-family-clang-objc-method-family" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the “method family”
+that a method belongs to.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(X)))</span></tt>, where <tt class="docutils literal"><span class="pre">X</span></tt> is one of
+<tt class="docutils literal"><span class="pre">none</span></tt>, <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>. This
+attribute can only be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="o">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="n">initMyStringValue</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_method_family</span><span class="p">(</span><span class="n">none</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>,
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>, etc).</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+</div>
+<div class="section" id="objc-requires-super-clang-objc-requires-super">
+<h3><a class="toc-backref" href="#id50">objc_requires_super (clang::objc_requires_super)</a><a class="headerlink" href="#objc-requires-super-clang-objc-requires-super" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a “call to <tt class="docutils literal"><span class="pre">super</span></tt>” in the overriding
+method in the subclass.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_requires_super))</span></tt>. This attribute can only
+be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">foo</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_requires_super</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+<tt class="docutils literal"><span class="pre">-dealloc</span></tt> where the call must appear at the end). It checks only that it
+exists.</p>
+<p>Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro <tt class="docutils literal"><span class="pre">NS_REQUIRES_SUPER</span></tt> that provides syntactic sugar for this
+attribute:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">foo</span> <span class="n">NS_REQUIRES_SUPER</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This macro is conditionally defined depending on the compiler’s support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.</p>
+<p>Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="nl">warning:</span> <span class="n">method</span> <span class="n">possibly</span> <span class="n">missing</span> <span class="n">a</span> <span class="p">[</span><span class="n">super</span> <span class="n">AnnotMeth</span><span class="p">]</span> <span class="n">call</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">AnnotMeth</span><span class="p">{};</span>
+ <span class="o">^</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-runtime-name-clang-objc-runtime-name">
+<h3><a class="toc-backref" href="#id51">objc_runtime_name (clang::objc_runtime_name)</a><a class="headerlink" href="#objc-runtime-name-clang-objc-runtime-name" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The <cite>objc_runtime_name</cite>
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object’s metadata name instead of the
+default name.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_runtime_name("MyLocalName")))</span></tt>. This attribute
+can only be placed before an @protocol or @interface declaration:</p>
+<div class="highlight-objc"><pre>__attribute__((objc_runtime_name("MyLocalName")))
+ at interface Message
+ at end</pre>
+</div>
+</div>
+<div class="section" id="objc-runtime-visible-clang-objc-runtime-visible">
+<h3><a class="toc-backref" href="#id52">objc_runtime_visible (clang::objc_runtime_visible)</a><a class="headerlink" href="#objc-runtime-visible-clang-objc-runtime-visible" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them.</p>
+</div>
+<div class="section" id="optnone-clang-optnone">
+<h3><a class="toc-backref" href="#id53">optnone (clang::optnone)</a><a class="headerlink" href="#optnone-clang-optnone" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">optnone</span></tt> attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole. This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization. Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.</p>
+<p>This attribute is incompatible with the <tt class="docutils literal"><span class="pre">always_inline</span></tt> and <tt class="docutils literal"><span class="pre">minsize</span></tt>
+attributes.</p>
+</div>
+<div class="section" id="overloadable-clang-overloadable">
+<h3><a class="toc-backref" href="#id54">overloadable (clang::overloadable)</a><a class="headerlink" href="#overloadable-clang-overloadable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. For example, one
+might provide several overloaded versions of a <tt class="docutils literal"><span class="pre">tgsin</span></tt> function that invokes
+the appropriate standard function computing the sine of a value with <tt class="docutils literal"><span class="pre">float</span></tt>,
+<tt class="docutils literal"><span class="pre">double</span></tt>, or <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> precision:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="kt">float</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinf</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">long</span> <span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">long</span> <span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinl</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Given these declarations, one can call <tt class="docutils literal"><span class="pre">tgsin</span></tt> with a <tt class="docutils literal"><span class="pre">float</span></tt> value to
+receive a <tt class="docutils literal"><span class="pre">float</span></tt> result, with a <tt class="docutils literal"><span class="pre">double</span></tt> to receive a <tt class="docutils literal"><span class="pre">double</span></tt> result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:</p>
+<ul class="simple">
+<li>Conversion from <tt class="docutils literal"><span class="pre">float</span></tt> or <tt class="docutils literal"><span class="pre">double</span></tt> to <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> is ranked as a
+floating-point promotion (per C99) rather than as a floating-point conversion
+(as in C++).</li>
+<li>A conversion from a pointer of type <tt class="docutils literal"><span class="pre">T*</span></tt> to a pointer of type <tt class="docutils literal"><span class="pre">U*</span></tt> is
+considered a pointer conversion (with conversion rank) if <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> are
+compatible types.</li>
+<li>A conversion from type <tt class="docutils literal"><span class="pre">T</span></tt> to a value of type <tt class="docutils literal"><span class="pre">U</span></tt> is permitted if <tt class="docutils literal"><span class="pre">T</span></tt>
+and <tt class="docutils literal"><span class="pre">U</span></tt> are compatible types. This conversion is given “conversion” rank.</li>
+<li>If no viable candidates are otherwise available, we allow a conversion from a
+pointer of type <tt class="docutils literal"><span class="pre">T*</span></tt> to a pointer of type <tt class="docutils literal"><span class="pre">U*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> are
+incompatible. This conversion is ranked below all other types of conversions.
+Please note: <tt class="docutils literal"><span class="pre">U</span></tt> lacking qualifiers that are present on <tt class="docutils literal"><span class="pre">T</span></tt> is sufficient
+for <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> to be incompatible.</li>
+</ul>
+<p>The declaration of <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions is restricted to function
+declarations and definitions. If a function is marked with the <tt class="docutils literal"><span class="pre">overloadable</span></tt>
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. In addition, redeclarations of a function with
+the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute must have the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, and
+redeclarations of a function without the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute must <em>not</em>
+have the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. e.g.,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">float</span> <span class="n">f</span><span class="p">(</span><span class="kt">float</span><span class="p">);</span> <span class="c1">// error: declaration of "f" must have the "overloadable" attribute</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span> <span class="c1">// error: redeclaration of "f" must have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="n">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="c1">// error: redeclaration of "g" must also have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="n">h</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">h</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: declaration of "h" must not</span>
+ <span class="c1">// have the "overloadable" attribute</span>
+</pre></div>
+</div>
+<p>Functions marked <tt class="docutils literal"><span class="pre">overloadable</span></tt> must have prototypes. Therefore, the
+following code is ill-formed:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">h</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: h does not have a prototype</span>
+</pre></div>
+</div>
+<p>However, <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the <tt class="docutils literal"><span class="pre">unavailable</span></tt> attribute:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">honeypot</span><span class="p">(...)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">,</span> <span class="n">unavailable</span><span class="p">));</span> <span class="c1">// calling me is an error</span>
+</pre></div>
+</div>
+<p>Functions declared with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+<tt class="docutils literal"><span class="pre">tgsin</span></tt> functions in our motivating example get the mangled names
+<tt class="docutils literal"><span class="pre">_Z5tgsinf</span></tt>, <tt class="docutils literal"><span class="pre">_Z5tgsind</span></tt>, and <tt class="docutils literal"><span class="pre">_Z5tgsine</span></tt>, respectively. There are two
+caveats to this use of name mangling:</p>
+<ul class="simple">
+<li>Future versions of Clang may change the name mangling of functions overloaded
+in C, so you should not depend on an specific mangling. To be completely
+safe, we strongly urge the use of <tt class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></tt> with <tt class="docutils literal"><span class="pre">overloadable</span></tt>
+functions.</li>
+<li>The <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute has almost no meaning when used in C++,
+because names will already be mangled and functions are already overloadable.
+However, when an <tt class="docutils literal"><span class="pre">overloadable</span></tt> function occurs within an <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt>
+linkage specification, it’s name <em>will</em> be mangled in the same way as it
+would in C.</li>
+</ul>
+<p>For the purpose of backwards compatibility, at most one function with the same
+name as other <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions may omit the <tt class="docutils literal"><span class="pre">overloadable</span></tt>
+attribute. In this case, the function without the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute
+will not have its name mangled.</p>
+<p>For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="c1">// Notes with mangled names assume Itanium mangling.</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">f</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> <span class="c1">// Emits a call to f (not _Z1fi, as it would with an overload that</span>
+ <span class="c1">// was marked with overloadable).</span>
+ <span class="n">f</span><span class="p">(</span><span class="mf">1.0</span><span class="p">);</span> <span class="c1">// Emits a call to _Z1fd.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Support for unmarked overloads is not present in some versions of clang. You may
+query for it using <tt class="docutils literal"><span class="pre">__has_extension(overloadable_unmarked)</span></tt>.</p>
+<p>Query for this attribute with <tt class="docutils literal"><span class="pre">__has_attribute(overloadable)</span></tt>.</p>
+</div>
+<div class="section" id="release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability">
+<h3><a class="toc-backref" href="#id55">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a><a class="headerlink" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as releasing a capability.</p>
+</div>
+<div class="section" id="short-call-gnu-short-call-gnu-near">
+<h3><a class="toc-backref" href="#id56">short_call (gnu::short_call, gnu::near)</a><a class="headerlink" href="#short-call-gnu-short-call-gnu-near" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((long_call))</span></tt>, <tt class="docutils literal"><span class="pre">__attribute__((far))</span></tt>,
+<tt class="docutils literal"><span class="pre">__attribute__((short__call))</span></tt>, and <tt class="docutils literal"><span class="pre">__attribute__((near))</span></tt> attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The <tt class="docutils literal"><span class="pre">short_call</span></tt> and <tt class="docutils literal"><span class="pre">near</span></tt> attributes are synonyms and
+allow calls to the function to be made using the <tt class="docutils literal"><span class="pre">jal</span></tt> instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller. The <tt class="docutils literal"><span class="pre">long_call</span></tt> and <tt class="docutils literal"><span class="pre">far</span></tt> attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.</p>
+<p>These attributes have no effect for position-independent code.</p>
+<p>These attributes take priority over command line switches such
+as <tt class="docutils literal"><span class="pre">-mlong-calls</span></tt> and <tt class="docutils literal"><span class="pre">-mno-long-calls</span></tt>.</p>
+</div>
+<div class="section" id="signal-gnu-signal">
+<h3><a class="toc-backref" href="#id57">signal (gnu::signal)</a><a class="headerlink" href="#signal-gnu-signal" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((signal))</span></tt> attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>Interrupt handler functions defined with the signal attribute do not re-enable interrupts.</p>
+</div>
+<div class="section" id="target-gnu-target">
+<h3><a class="toc-backref" href="#id58">target (gnu::target)</a><a class="headerlink" href="#target-gnu-target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((target("OPTIONS")))</span></tt> attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.</p>
+<p>The current set of options correspond to the existing “subtarget features” for
+the target with or without a “-mno-” in front corresponding to the absence
+of the feature, as well as <tt class="docutils literal"><span class="pre">arch="CPU"</span></tt> which will change the default “CPU”
+for the function.</p>
+<p>Example “subtarget features” from the x86 backend include: “mmx”, “sse”, “sse4.2”,
+“avx”, “xop” and largely correspond to the machine specific options handled by
+the front end.</p>
+</div>
+<div class="section" id="try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id59">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a><a class="headerlink" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).</p>
+</div>
+<div class="section" id="xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument-xray-log-args-clang-xray-log-args">
+<h3><a class="toc-backref" href="#id60">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)</a><a class="headerlink" href="#xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument-xray-log-args-clang-xray-log-args" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((xray_always_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_always_instrument]]</span></tt> is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.</p>
+<p>Conversely, <tt class="docutils literal"><span class="pre">__attribute__((xray_never_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_never_instrument]]</span></tt> will inhibit the insertion of these instrumentation points.</p>
+<p>If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.</p>
+<p><tt class="docutils literal"><span class="pre">__attribute__((xray_log_args(N)))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_log_args(N)]]</span></tt> is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id61">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((xray_always_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_always_instrument]]</span></tt> is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.</p>
+<p>Conversely, <tt class="docutils literal"><span class="pre">__attribute__((xray_never_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_never_instrument]]</span></tt> will inhibit the insertion of these instrumentation points.</p>
+<p>If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.</p>
+<p><tt class="docutils literal"><span class="pre">__attribute__((xray_log_args(N)))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_log_args(N)]]</span></tt> is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.</p>
+</div>
+</div>
+<div class="section" id="variable-attributes">
+<h2><a class="toc-backref" href="#id62">Variable Attributes</a><a class="headerlink" href="#variable-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="dllexport-gnu-dllexport">
+<h3><a class="toc-backref" href="#id63">dllexport (gnu::dllexport)</a><a class="headerlink" href="#dllexport-gnu-dllexport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> attribute declares a variable, function, or
+Objective-C interface to be exported from the module. It is available under the
+<tt class="docutils literal"><span class="pre">-fdeclspec</span></tt> flag for compatibility with various compilers. The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use. See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllexport</a> documentation on MSDN for more
+information.</p>
+</div>
+<div class="section" id="dllimport-gnu-dllimport">
+<h3><a class="toc-backref" href="#id64">dllimport (gnu::dllimport)</a><a class="headerlink" href="#dllimport-gnu-dllimport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> attribute declares a variable, function, or
+Objective-C interface to be imported from an external module. It is available
+under the <tt class="docutils literal"><span class="pre">-fdeclspec</span></tt> flag for compatibility with various compilers. The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules. See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllimport</a> documentation on MSDN
+for more information.</p>
+</div>
+<div class="section" id="init-seg">
+<h3><a class="toc-backref" href="#id65">init_seg</a><a class="headerlink" href="#init-seg" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The attribute applied by <tt class="docutils literal"><span class="pre">pragma</span> <span class="pre">init_seg()</span></tt> controls the section into
+which global initialization function pointers are emitted. It is only
+available with <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt>. Typically, this function pointer is
+emitted into <tt class="docutils literal"><span class="pre">.CRT$XCU</span></tt> on Windows. The user can change the order of
+initialization by using a different section name with the same
+<tt class="docutils literal"><span class="pre">.CRT$XC</span></tt> prefix and a suffix that sorts lexicographically before or
+after the standard <tt class="docutils literal"><span class="pre">.CRT$XCU</span></tt> sections. See the <a class="reference external" href="http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx">init_seg</a>
+documentation on MSDN for more information.</p>
+</div>
+<div class="section" id="maybe-unused-unused-gnu-unused">
+<h3><a class="toc-backref" href="#id66">maybe_unused, unused, gnu::unused</a><a class="headerlink" href="#maybe-unused-unused-gnu-unused" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When passing the <tt class="docutils literal"><span class="pre">-Wunused</span></tt> flag to Clang, entities that are unused by the
+program may be diagnosed. The <tt class="docutils literal"><span class="pre">[[maybe_unused]]</span></tt> (or
+<tt class="docutils literal"><span class="pre">__attribute__((unused))</span></tt>) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an <tt class="docutils literal"><span class="pre">assert()</span></tt> statement, which makes the local variable
+unused when <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> is defined.</p>
+<p>The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.</p>
+</div>
+<div class="section" id="nodebug-gnu-nodebug">
+<h3><a class="toc-backref" href="#id67">nodebug (gnu::nodebug)</a><a class="headerlink" href="#nodebug-gnu-nodebug" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">nodebug</span></tt> attribute allows you to suppress debugging information for a
+function or method, or for a variable that is not a parameter or a non-static
+data member.</p>
+</div>
+<div class="section" id="noescape-clang-noescape">
+<h3><a class="toc-backref" href="#id68">noescape (clang::noescape)</a><a class="headerlink" href="#noescape-clang-noescape" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">noescape</span></tt> placed on a function parameter of a pointer type is used to inform
+the compiler that the pointer cannot escape: that is, no reference to the object
+the pointer points to that is derived from the parameter value will survive
+after the function returns. Users are responsible for making sure parameters
+annotated with <tt class="docutils literal"><span class="pre">noescape</span></tt> do not actuallly escape.</p>
+<p>For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="o">*</span><span class="n">gp</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">nonescapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">*</span><span class="n">p</span> <span class="o">+=</span> <span class="mi">100</span><span class="p">;</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">escapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">gp</span> <span class="o">=</span> <span class="n">p</span><span class="p">;</span> <span class="c1">// Not OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Additionally, when the parameter is a <cite>block pointer
+<https://clang.llvm.org/docs/BlockLanguageSpec.html></cite>, the same restriction
+applies to copies of the block. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">BlockTy</span><span class="p">)();</span>
+<span class="n">BlockTy</span> <span class="n">g0</span><span class="p">,</span> <span class="n">g1</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">nonescapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="n">BlockTy</span> <span class="n">block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">block</span><span class="p">();</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">escapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="n">BlockTy</span> <span class="n">block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">g0</span> <span class="o">=</span> <span class="n">block</span><span class="p">;</span> <span class="c1">// Not OK.</span>
+ <span class="n">g1</span> <span class="o">=</span> <span class="n">Block_copy</span><span class="p">(</span><span class="n">block</span><span class="p">);</span> <span class="c1">// Not OK either.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nosvm">
+<h3><a class="toc-backref" href="#id69">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>OpenCL 2.0 supports the optional <tt class="docutils literal"><span class="pre">__attribute__((nosvm))</span></tt> qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.</p>
+<p>Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.</p>
+</div>
+<div class="section" id="pass-object-size-clang-pass-object-size">
+<h3><a class="toc-backref" href="#id70">pass_object_size (clang::pass_object_size)</a><a class="headerlink" href="#pass-object-size-clang-pass-object-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The mangling of functions with parameters that are annotated with
+<tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is subject to change. You can get around this by
+using <tt class="docutils literal"><span class="pre">__asm__("foo")</span></tt> to explicitly name your functions, thus preserving
+your ABI; also, non-overloadable C functions with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> are
+not mangled.</p>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">pass_object_size(Type)</span></tt> attribute can be placed on function parameters to
+instruct clang to call <tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type <tt class="docutils literal"><span class="pre">size_t</span></tt> directly after the parameter annotated with
+<tt class="docutils literal"><span class="pre">pass_object_size</span></tt>. Clang will also replace any calls to
+<tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> in the function by said implicit
+parameter.</p>
+<p>Example usage:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">bzero1</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">pass_object_size</span><span class="p">(</span><span class="mi">0</span><span class="p">))))</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">noinline</span><span class="p">))</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="cm">/**/</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">p</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">char</span> <span class="n">chars</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span>
+ <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="o">&</span><span class="n">chars</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">chars</span><span class="p">));</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If successfully evaluating <tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> at the
+callsite is not possible, then the “failed” value is passed in. So, using the
+definition of <tt class="docutils literal"><span class="pre">bzero1</span></tt> from above, the following code would exit cleanly:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main2</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="n">argv</span><span class="p">);</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">pass_object_size</span></tt> plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is preferred. This implies that the choice
+between two identical overloads both with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define PS(N) __attribute__((pass_object_size(N)))</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="n">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span> <span class="c1">// Overload A</span>
+<span class="c1">// OK -- overload A has no parameters with pass_object_size.</span>
+<span class="kt">void</span> <span class="n">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload B</span>
+<span class="c1">// Error -- Same signature (sans pass_object_size) as overload B, and both</span>
+<span class="c1">// overloads have one or more parameters with the pass_object_size attribute.</span>
+<span class="kt">void</span> <span class="n">Foo</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span>
+
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="n">Bar</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload C</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="n">Bar</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">c</span> <span class="n">PS</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span> <span class="c1">// Overload D</span>
+
+<span class="kt">void</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">char</span> <span class="n">known</span><span class="p">[</span><span class="mi">10</span><span class="p">],</span> <span class="o">*</span><span class="n">unknown</span><span class="p">;</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+
+ <span class="n">Bar</span><span class="p">(</span><span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+ <span class="n">Bar</span><span class="p">(</span><span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Currently, <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is a bit restricted in terms of its usage:</p>
+<ul class="simple">
+<li>Only one use of <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is allowed per parameter.</li>
+<li>It is an error to take the address of a function with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on
+any of its parameters. If you wish to do this, you can create an overload
+without <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on any parameters.</li>
+<li>It is an error to apply the <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> attribute to parameters that
+are not pointers. Additionally, any parameter that <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is
+applied to must be marked <tt class="docutils literal"><span class="pre">const</span></tt> at its function’s definition.</li>
+</ul>
+</div>
+<div class="section" id="require-constant-initialization-clang-require-constant-initialization">
+<h3><a class="toc-backref" href="#id71">require_constant_initialization (clang::require_constant_initialization)</a><a class="headerlink" href="#require-constant-initialization-clang-require-constant-initialization" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the variable to which it is attached is intended
+to have a <a class="reference external" href="http://en.cppreference.com/w/cpp/language/constant_initialization">constant initializer</a>
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.</p>
+<p>Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it’s
+not technically a ‘constant initializer’. This behavior is non-portable.</p>
+<p>Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.</p>
+<p>This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it’s important to fail fast instead
+of silently falling back on dynamic initialization.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">// -std=c++14</span>
+<span class="cp">#define SAFE_STATIC [[clang::require_constant_initialization]]</span>
+<span class="k">struct</span> <span class="n">T</span> <span class="p">{</span>
+ <span class="n">constexpr</span> <span class="n">T</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="o">~</span><span class="n">T</span><span class="p">();</span> <span class="c1">// non-trivial</span>
+<span class="p">};</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">x</span> <span class="o">=</span> <span class="p">{</span><span class="mi">42</span><span class="p">};</span> <span class="c1">// Initialization OK. Doesn't check destructor.</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// error: variable does not have a constant initializer</span>
+<span class="c1">// copy initialization is not a constant expression on a non-literal type.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-gnu-section-declspec-allocate">
+<h3><a class="toc-backref" href="#id72">section (gnu::section, __declspec(allocate))</a><a class="headerlink" href="#section-gnu-section-declspec-allocate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">section</span></tt> attribute allows you to specify a specific section a
+global variable or function should be in after translation.</p>
+</div>
+<div class="section" id="swift-context-clang-swift-context">
+<h3><a class="toc-backref" href="#id73">swift_context (clang::swift_context)</a><a class="headerlink" href="#swift-context-clang-swift-context" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_context</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special context-parameter ABI treatment.</p>
+<p>This treatment generally passes the context value in a special register
+which is normally callee-preserved.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_context</span></tt> parameter must either be the last parameter or must be
+followed by a <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter (which itself must always be
+the last parameter).</p>
+<p>A context parameter must have pointer or reference type.</p>
+</div>
+<div class="section" id="swift-error-result-clang-swift-error-result">
+<h3><a class="toc-backref" href="#id74">swift_error_result (clang::swift_error_result)</a><a class="headerlink" href="#swift-error-result-clang-swift-error-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special error-result ABI treatment.</p>
+<p>This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:</p>
+<ul class="simple">
+<li>The caller appears to pass the address of a variable of pointer type.
+The current value of this variable is copied into the register before
+the call; if the call returns normally, the value is copied back into the
+variable.</li>
+<li>The callee appears to receive the address of a variable. This address
+is actually a hidden location in its own stack, initialized with the
+value of the register upon entry. When the function returns normally,
+the value in that hidden location is written back to the register.</li>
+</ul>
+<p>A <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter must be the last parameter, and it must be
+preceded by a <tt class="docutils literal"><span class="pre">swift_context</span></tt> parameter.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter must have type <tt class="docutils literal"><span class="pre">T**</span></tt> or <tt class="docutils literal"><span class="pre">T*&</span></tt> for some
+type T. Note that no qualifiers are permitted on the intermediate level.</p>
+<p>It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.</p>
+<p>The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.</p>
+</div>
+<div class="section" id="swift-indirect-result-clang-swift-indirect-result">
+<h3><a class="toc-backref" href="#id75">swift_indirect_result (clang::swift_indirect_result)</a><a class="headerlink" href="#swift-indirect-result-clang-swift-indirect-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special indirect-result ABI treatment.</p>
+<p>This treatment gives the parameter the target’s normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter. However, only the first indirect result will receive this
+treatment. Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+<tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameters.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter must either be the first parameter or
+follow another <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter must have type <tt class="docutils literal"><span class="pre">T*</span></tt> or <tt class="docutils literal"><span class="pre">T&</span></tt> for
+some object type <tt class="docutils literal"><span class="pre">T</span></tt>. If <tt class="docutils literal"><span class="pre">T</span></tt> is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
+<p>Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++’s named return value optimization (NRVO).</p>
+</div>
+<div class="section" id="swiftcall-clang-swiftcall">
+<h3><a class="toc-backref" href="#id76">swiftcall (clang::swiftcall)</a><a class="headerlink" href="#swiftcall-clang-swiftcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swiftcall</span></tt> attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.</p>
+<p>The lowering for the Swift calling convention, as described by the Swift
+ABI documentation, occurs in multiple phases. The first, “high-level”
+phase breaks down the formal parameters and results into innately direct
+and indirect components, adds implicit paraameters for the generic
+signature, and assigns the context and error ABI treatments to parameters
+where applicable. The second phase breaks down the direct parameters
+and results from the first phase and assigns them to registers or the
+stack. The <tt class="docutils literal"><span class="pre">swiftcall</span></tt> convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:</p>
+<ul class="simple">
+<li>Results classified as indirect by high-level lowering should be
+represented as parameters with the <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> attribute.</li>
+<li>Results classified as direct by high-level lowering should be represented
+as follows:<ul>
+<li>First, remove any empty direct results.</li>
+<li>If there are no direct results, the C result type should be <tt class="docutils literal"><span class="pre">void</span></tt>.</li>
+<li>If there is one direct result, the C result type should be a type with
+the exact layout of that result type.</li>
+<li>If there are a multiple direct results, the C result type should be
+a struct type with the exact layout of a tuple of those results.</li>
+</ul>
+</li>
+<li>Parameters classified as indirect by high-level lowering should be
+represented as parameters of pointer type.</li>
+<li>Parameters classified as direct by high-level lowering should be
+omitted if they are empty types; otherwise, they should be represented
+as a parameter type with a layout exactly matching the layout of the
+Swift parameter type.</li>
+<li>The context parameter, if present, should be represented as a trailing
+parameter with the <tt class="docutils literal"><span class="pre">swift_context</span></tt> attribute.</li>
+<li>The error result parameter, if present, should be represented as a
+trailing parameter (always following a context parameter) with the
+<tt class="docutils literal"><span class="pre">swift_error_result</span></tt> attribute.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">swiftcall</span></tt> does not support variadic arguments or unprototyped functions.</p>
+<p>The parameter ABI treatment attributes are aspects of the function type.
+A function type which which applies an ABI treatment attribute to a
+parameter is a different type from an otherwise-identical function type
+that does not. A single parameter may not have multiple ABI treatment
+attributes.</p>
+<p>Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports. Query for this support
+with <tt class="docutils literal"><span class="pre">__has_attribute(swiftcall)</span></tt>. This implies support for the
+<tt class="docutils literal"><span class="pre">swift_context</span></tt>, <tt class="docutils literal"><span class="pre">swift_error_result</span></tt>, and <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt>
+attributes.</p>
+</div>
+<div class="section" id="thread">
+<h3><a class="toc-backref" href="#id77">thread</a><a class="headerlink" href="#thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> attribute declares a variable with thread local
+storage. It is available under the <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> flag for MSVC
+compatibility. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx">__declspec(thread)</a> on MSDN.</p>
+<p>In Clang, <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> is generally equivalent in functionality to the
+GNU <tt class="docutils literal"><span class="pre">__thread</span></tt> keyword. The variable must not have a destructor and must have
+a constant initializer, if any. The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.</p>
+</div>
+<div class="section" id="tls-model-gnu-tls-model">
+<h3><a class="toc-backref" href="#id78">tls_model (gnu::tls_model)</a><a class="headerlink" href="#tls-model-gnu-tls-model" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:</p>
+<ul class="simple">
+<li>global-dynamic</li>
+<li>local-dynamic</li>
+<li>initial-exec</li>
+<li>local-exec</li>
+</ul>
+<p>TLS models are mutually exclusive.</p>
+</div>
+</div>
+<div class="section" id="type-attributes">
+<h2><a class="toc-backref" href="#id79">Type Attributes</a><a class="headerlink" href="#type-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="single-inhertiance-multiple-inheritance-virtual-inheritance">
+<h3><a class="toc-backref" href="#id80">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a><a class="headerlink" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This collection of keywords is enabled under <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> and controls
+the pointer-to-member representation used on <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets.</p>
+<p>The <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.</p>
+<p>However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.</p>
+<p>These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.</p>
+<p>This family of keywords belong between the <tt class="docutils literal"><span class="pre">class-key</span></tt> and <tt class="docutils literal"><span class="pre">class-name</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="kr">__single_inheritance</span> <span class="n">S</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+<p>This keyword can be applied to class templates but only has an effect when used
+on full specializations:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="p">,</span> <span class="k">typename</span> <span class="n">U</span><span class="o">></span> <span class="k">struct</span> <span class="kr">__single_inheritance</span> <span class="n">A</span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on primary template</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="k">struct</span> <span class="kr">__multiple_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="o">></span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on partial specialization</span>
+<span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="kr">__single_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">float</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Note that choosing an inheritance model less general than strictly necessary is
+an error:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="kr">__multiple_inheritance</span> <span class="n">S</span><span class="p">;</span> <span class="c1">// error: inheritance model does not match definition</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="align-value">
+<h3><a class="toc-backref" href="#id81">align_value</a><a class="headerlink" href="#align-value" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">double</span> <span class="o">*</span> <span class="n">aligned_double_ptr</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">64</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">double</span> <span class="o">&</span> <span class="n">x</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">128</span><span class="p">)),</span>
+ <span class="n">aligned_double_ptr</span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.</p>
+</div>
+<div class="section" id="empty-bases">
+<h3><a class="toc-backref" href="#id82">empty_bases</a><a class="headerlink" href="#empty-bases" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="enum-extensibility-clang-enum-extensibility">
+<h3><a class="toc-backref" href="#id83">enum_extensibility (clang::enum_extensibility)</a><a class="headerlink" href="#enum-extensibility-clang-enum-extensibility" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Attribute <tt class="docutils literal"><span class="pre">enum_extensibility</span></tt> is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+<tt class="docutils literal"><span class="pre">closed</span></tt> or <tt class="docutils literal"><span class="pre">open</span></tt> as an argument. <tt class="docutils literal"><span class="pre">closed</span></tt> indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with <tt class="docutils literal"><span class="pre">flag_enum</span></tt>, a value that
+can be constructed using values corresponding to the enumerators. <tt class="docutils literal"><span class="pre">open</span></tt>
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">closed</span><span class="p">)))</span> <span class="n">ClosedEnum</span> <span class="p">{</span>
+ <span class="n">A0</span><span class="p">,</span> <span class="n">A1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">open</span><span class="p">)))</span> <span class="n">OpenEnum</span> <span class="p">{</span>
+ <span class="n">B0</span><span class="p">,</span> <span class="n">B1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">closed</span><span class="p">),</span><span class="n">flag_enum</span><span class="p">))</span> <span class="n">ClosedFlagEnum</span> <span class="p">{</span>
+ <span class="n">C0</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> <span class="n">C1</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">open</span><span class="p">),</span><span class="n">flag_enum</span><span class="p">))</span> <span class="n">OpenFlagEnum</span> <span class="p">{</span>
+ <span class="n">D0</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> <span class="n">D1</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">foo1</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">enum</span> <span class="n">ClosedEnum</span> <span class="n">ce</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">OpenEnum</span> <span class="n">oe</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">ClosedFlagEnum</span> <span class="n">cfe</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">OpenFlagEnum</span> <span class="n">ofe</span><span class="p">;</span>
+
+ <span class="n">ce</span> <span class="o">=</span> <span class="n">A1</span><span class="p">;</span> <span class="c1">// no warnings</span>
+ <span class="n">ce</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> <span class="c1">// warning issued</span>
+ <span class="n">oe</span> <span class="o">=</span> <span class="n">B1</span><span class="p">;</span> <span class="c1">// no warnings</span>
+ <span class="n">oe</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> <span class="c1">// no warnings</span>
+ <span class="n">cfe</span> <span class="o">=</span> <span class="n">C0</span> <span class="o">|</span> <span class="n">C1</span><span class="p">;</span> <span class="c1">// no warnings</span>
+ <span class="n">cfe</span> <span class="o">=</span> <span class="n">C0</span> <span class="o">|</span> <span class="n">C1</span> <span class="o">|</span> <span class="mi">4</span><span class="p">;</span> <span class="c1">// warning issued</span>
+ <span class="n">ofe</span> <span class="o">=</span> <span class="n">D0</span> <span class="o">|</span> <span class="n">D1</span><span class="p">;</span> <span class="c1">// no warnings</span>
+ <span class="n">ofe</span> <span class="o">=</span> <span class="n">D0</span> <span class="o">|</span> <span class="n">D1</span> <span class="o">|</span> <span class="mi">4</span><span class="p">;</span> <span class="c1">// no warnings</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="flag-enum-clang-flag-enum">
+<h3><a class="toc-backref" href="#id84">flag_enum (clang::flag_enum)</a><a class="headerlink" href="#flag-enum-clang-flag-enum" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.</p>
+</div>
+<div class="section" id="layout-version">
+<h3><a class="toc-backref" href="#id85">layout_version</a><a class="headerlink" href="#layout-version" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="lto-visibility-public-clang-lto-visibility-public">
+<h3><a class="toc-backref" href="#id86">lto_visibility_public (clang::lto_visibility_public)</a><a class="headerlink" href="#lto-visibility-public-clang-lto-visibility-public" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>See <a class="reference internal" href="LTOVisibility.html"><em>LTO Visibility</em></a>.</p>
+</div>
+<div class="section" id="novtable">
+<h3><a class="toc-backref" href="#id87">novtable</a><a class="headerlink" href="#novtable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table. It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="objc-subclassing-restricted-clang-objc-subclassing-restricted">
+<h3><a class="toc-backref" href="#id88">objc_subclassing_restricted (clang::objc_subclassing_restricted)</a><a class="headerlink" href="#objc-subclassing-restricted-clang-objc-subclassing-restricted" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an Objective-C <tt class="docutils literal"><span class="pre">@interface</span></tt> declaration to
+ensure that this class cannot be subclassed.</p>
+</div>
+<div class="section" id="selectany-gnu-selectany">
+<h3><a class="toc-backref" href="#id89">selectany (gnu::selectany)</a><a class="headerlink" href="#selectany-gnu-selectany" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute appertains to a global symbol, causing it to have a weak
+definition (
+<a class="reference external" href="https://llvm.org/docs/LangRef.html#linkage-types">linkonce</a>
+), allowing the linker to select any definition.</p>
+<p>For more information see
+<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html">gcc documentation</a>
+or <a class="reference external" href="https://docs.microsoft.com/pl-pl/cpp/cpp/selectany">msvc documentation</a>.</p>
+</div>
+<div class="section" id="transparent-union-gnu-transparent-union">
+<h3><a class="toc-backref" href="#id90">transparent_union (gnu::transparent_union)</a><a class="headerlink" href="#transparent-union-gnu-transparent-union" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:</p>
+<ul class="simple">
+<li>A value whose type is any member of the transparent union can be passed as an
+argument without the need to cast that value.</li>
+<li>The argument is passed to the function using the calling convention of the
+first member of the transparent union. Consequently, all the members of the
+transparent union should have the same calling convention as its first member.</li>
+</ul>
+<p>Transparent unions are not supported in C++.</p>
+</div>
+</div>
+<div class="section" id="statement-attributes">
+<h2><a class="toc-backref" href="#id91">Statement Attributes</a><a class="headerlink" href="#statement-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="pragma-clang-loop">
+<h3><a class="toc-backref" href="#id92">#pragma clang loop</a><a class="headerlink" href="#pragma-clang-loop" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></tt> directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for details.</p>
+</div>
+<div class="section" id="pragma-unroll-pragma-nounroll">
+<h3><a class="toc-backref" href="#id93">#pragma unroll, #pragma nounroll</a><a class="headerlink" href="#pragma-unroll-pragma-nounroll" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Loop unrolling optimization hints can be specified with <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> and
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt>. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.</p>
+<p>Specifying <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time and
+attempt to partially unroll the loop if the trip count is not known at compile
+time:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma unroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying the optional parameter, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></tt>, directs the
+unroller to unroll the loop <tt class="docutils literal"><span class="pre">_value_</span></tt> times. The parameter may optionally be
+enclosed in parentheses:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma unroll 16</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="cp">#pragma unroll(16)</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt> indicates that the loop should not be unrolled:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma nounroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></tt> have identical semantics to
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(full)</span></tt> and
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll_count(_value_)</span></tt> respectively. <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt>
+is equivalent to <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(disable)</span></tt>. See
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for further details including limitations of the unroll hints.</p>
+</div>
+<div class="section" id="attribute-intel-reqd-sub-group-size">
+<h3><a class="toc-backref" href="#id94">__attribute__((intel_reqd_sub_group_size))</a><a class="headerlink" href="#attribute-intel-reqd-sub-group-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See <cite>cl_intel_required_subgroup_size
+<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt></cite>
+for details.</p>
+</div>
+<div class="section" id="attribute-opencl-unroll-hint">
+<h3><a class="toc-backref" href="#id95">__attribute__((opencl_unroll_hint))</a><a class="headerlink" href="#attribute-opencl-unroll-hint" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The opencl_unroll_hint attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf">OpenCL v2.0</a>
+s6.11.5 for details.</p>
+</div>
+<div class="section" id="read-only-write-only-read-write-read-only-write-only-read-write">
+<h3><a class="toc-backref" href="#id96">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a><a class="headerlink" href="#read-only-write-only-read-write-read-only-write-only-read-write" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.</p>
+<p>The read_only/__read_only, write_only/__write_only and read_write/__read_write
+names are reserved for use as access qualifiers and shall not be used otherwise.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">kernel</span> <span class="kt">void</span>
+<span class="nf">foo</span> <span class="p">(</span><span class="n">read_only</span> <span class="n">image2d_t</span> <span class="n">imageA</span><span class="p">,</span>
+ <span class="n">write_only</span> <span class="n">image2d_t</span> <span class="n">imageB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.</p>
+<p>The read_write (or __read_write) qualifier can not be used with pipe.</p>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.6.</p>
+</div>
+<div class="section" id="fallthrough-clang-fallthrough">
+<h3><a class="toc-backref" href="#id97">fallthrough, clang::fallthrough</a><a class="headerlink" href="#fallthrough-clang-fallthrough" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">fallthrough</span></tt> (or <tt class="docutils literal"><span class="pre">clang::fallthrough</span></tt>) attribute is used
+to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn’t change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like <tt class="docutils literal"><span class="pre">break;</span></tt>, so it can be placed in most places
+where <tt class="docutils literal"><span class="pre">break;</span></tt> can, but only if there are no statements on the execution path
+between it and the next switch label.</p>
+<p>By default, Clang does not warn on unannotated fallthrough from one <tt class="docutils literal"><span class="pre">switch</span></tt>
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the <tt class="docutils literal"><span class="pre">-Wimplicit-fallthrough</span></tt> argument.</p>
+<p>Here is an example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// compile with -Wimplicit-fallthrough</span>
+<span class="k">switch</span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="mi">22</span><span class="o">:</span>
+<span class="k">case</span> <span class="mi">33</span><span class="o">:</span> <span class="c1">// no warning: no statements between case labels</span>
+ <span class="n">f</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">44</span><span class="o">:</span> <span class="c1">// warning: unannotated fall-through</span>
+ <span class="n">g</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+<span class="k">case</span> <span class="mi">55</span><span class="o">:</span> <span class="c1">// no warning</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">h</span><span class="p">();</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="n">i</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+ <span class="p">}</span>
+<span class="k">case</span> <span class="mi">66</span><span class="o">:</span> <span class="c1">// no warning</span>
+ <span class="n">p</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span> <span class="c1">// warning: fallthrough annotation does not</span>
+ <span class="c1">// directly precede case label</span>
+ <span class="n">q</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">77</span><span class="o">:</span> <span class="c1">// warning: unannotated fall-through</span>
+ <span class="n">r</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="suppress-gsl-suppress">
+<h3><a class="toc-backref" href="#id98">suppress (gsl::suppress)</a><a class="headerlink" href="#suppress-gsl-suppress" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">[[gsl::suppress]]</span></tt> attribute suppresses specific
+clang-tidy diagnostics for rules of the <a class="reference external" href="https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement">C++ Core Guidelines</a> in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">[[</span><span class="n">gsl</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"Rh-public"</span><span class="p">)]]</span>
+<span class="kt">void</span> <span class="n">f_</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
+ <span class="p">[[</span><span class="n">gsl</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"type"</span><span class="p">)]]</span> <span class="p">{</span>
+ <span class="n">p</span> <span class="o">=</span> <span class="k">reinterpret_cast</span><span class="o"><</span><span class="kt">int</span><span class="o">*></span><span class="p">(</span><span class="mi">7</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"type"</span><span class="p">,</span> <span class="s">"bounds"</span><span class="p">)]];</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h2><a class="toc-backref" href="#id99">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.</p>
+<div class="section" id="fastcall-gnu-fastcall-fastcall-fastcall">
+<h3><a class="toc-backref" href="#id100">fastcall (gnu::fastcall, __fastcall, _fastcall)</a><a class="headerlink" href="#fastcall-gnu-fastcall-fastcall-fastcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the <tt class="docutils literal"><span class="pre">regparm</span></tt> attribute, which does
+not require callee-cleanup. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/6xa169sk.aspx">__fastcall</a> on MSDN.</p>
+</div>
+<div class="section" id="ms-abi-gnu-ms-abi">
+<h3><a class="toc-backref" href="#id101">ms_abi (gnu::ms_abi)</a><a class="headerlink" href="#ms-abi-gnu-ms-abi" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On non-Windows x86_64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows x86_64. This
+attribute has no effect on Windows targets or non-x86_64 targets.</p>
+</div>
+<div class="section" id="pcs-gnu-pcs">
+<h3><a class="toc-backref" href="#id102">pcs (gnu::pcs)</a><a class="headerlink" href="#pcs-gnu-pcs" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On ARM targets, this attribute can be used to select calling conventions
+similar to <tt class="docutils literal"><span class="pre">stdcall</span></tt> on x86. Valid parameter values are “aapcs” and
+“aapcs-vfp”.</p>
+</div>
+<div class="section" id="preserve-all-clang-preserve-all">
+<h3><a class="toc-backref" href="#id103">preserve_all (clang::preserve_all)</a><a class="headerlink" href="#preserve-all-clang-preserve-all" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <tt class="docutils literal"><span class="pre">preserve_all</span></tt> calling convention attempts to make the code
+in the caller even less intrusive than the <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention.
+This calling convention also behaves identical to the <tt class="docutils literal"><span class="pre">C</span></tt> calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn’t apply for values
+returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Furthermore it also preserves
+all floating-point registers (XMMs/YMMs).</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that don’t need to call out to any other functions.</p>
+<p>This calling convention, like the <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.</p>
+</div>
+<div class="section" id="preserve-most-clang-preserve-most">
+<h3><a class="toc-backref" href="#id104">preserve_most (clang::preserve_most)</a><a class="headerlink" href="#preserve-most-clang-preserve-most" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the <tt class="docutils literal"><span class="pre">C</span></tt> calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn’t
+apply for values returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Floating-point registers
+(XMMs/YMMs) are not preserved and need to be saved by the caller.</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that have a hot path and a cold path. The hot path is usually a small piece
+of code that doesn’t use many registers. The cold path might need to call out to
+another function and therefore only needs to preserve the caller-saved
+registers, which haven’t already been saved by the caller. The
+<cite>preserve_most</cite> calling convention is very similar to the <tt class="docutils literal"><span class="pre">cold</span></tt> calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. <tt class="docutils literal"><span class="pre">coldcc</span></tt> is for function calls that are
+rarely executed, whereas <cite>preserve_most</cite> function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore <tt class="docutils literal"><span class="pre">preserve_most</span></tt>
+doesn’t prevent the inliner from inlining the function call.</p>
+<p>This calling convention will be used by a future version of the Objective-C
+runtime and should therefore still be considered experimental at this time.
+Although this convention was created to optimize certain runtime calls to
+the Objective-C runtime, it is not limited to this runtime and might be used
+by other runtimes in the future too. The current implementation only
+supports X86-64 and AArch64, but the intention is to support more architectures
+in the future.</p>
+</div>
+<div class="section" id="regcall-gnu-regcall-regcall">
+<h3><a class="toc-backref" href="#id105">regcall (gnu::regcall, __regcall)</a><a class="headerlink" href="#regcall-gnu-regcall-regcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On x86 targets, this attribute changes the calling convention to
+<a class="reference external" href="https://software.intel.com/en-us/node/693069">__regcall</a> convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.</p>
+</div>
+<div class="section" id="regparm-gnu-regparm">
+<h3><a class="toc-backref" href="#id106">regparm (gnu::regparm)</a><a class="headerlink" href="#regparm-gnu-regparm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.</p>
+</div>
+<div class="section" id="stdcall-gnu-stdcall-stdcall-stdcall">
+<h3><a class="toc-backref" href="#id107">stdcall (gnu::stdcall, __stdcall, _stdcall)</a><a class="headerlink" href="#stdcall-gnu-stdcall-stdcall-stdcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx">__stdcall</a> on MSDN.</p>
+</div>
+<div class="section" id="thiscall-gnu-thiscall-thiscall-thiscall">
+<h3><a class="toc-backref" href="#id108">thiscall (gnu::thiscall, __thiscall, _thiscall)</a><a class="headerlink" href="#thiscall-gnu-thiscall-thiscall-thiscall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit <tt class="docutils literal"><span class="pre">this</span></tt>
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx">__thiscall</a> on
+MSDN.</p>
+</div>
+<div class="section" id="vectorcall-clang-vectorcall-vectorcall-vectorcall">
+<h3><a class="toc-backref" href="#id109">vectorcall (clang::vectorcall, __vectorcall, _vectorcall)</a><a class="headerlink" href="#vectorcall-clang-vectorcall-vectorcall-vectorcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 <em>and</em> x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.</p>
+<p>On 32-bit x86 targets, this calling convention is similar to <tt class="docutils literal"><span class="pre">__fastcall</span></tt>.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack. On x86_64
+targets, the callee does <em>not</em> clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.</p>
+<p>On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.</p>
+<p>See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/dn375768.aspx">__vectorcall</a> on MSDN for more details.</p>
+</div>
+</div>
+<div class="section" id="amd-gpu-attributes">
+<h2><a class="toc-backref" href="#id110">AMD GPU Attributes</a><a class="headerlink" href="#amd-gpu-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="amdgpu-flat-work-group-size-clang-amdgpu-flat-work-group-size">
+<h3><a class="toc-backref" href="#id111">amdgpu_flat_work_group_size (clang::amdgpu_flat_work_group_size)</a><a class="headerlink" href="#amdgpu-flat-work-group-size-clang-amdgpu-flat-work-group-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.</p>
+<p>Clang supports the
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_flat_work_group_size(<min>,</span> <span class="pre"><max>)))</span></tt> attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.</p>
+<p><tt class="docutils literal"><span class="pre"><min></span></tt> parameter specifies the minimum flat work-group size, and <tt class="docutils literal"><span class="pre"><max></span></tt>
+parameter specifies the maximum flat work-group size (must be greater than
+<tt class="docutils literal"><span class="pre"><min></span></tt>) to which all dispatches of the kernel will conform. Passing <tt class="docutils literal"><span class="pre">0,</span> <span class="pre">0</span></tt>
+as <tt class="docutils literal"><span class="pre"><min>,</span> <span class="pre"><max></span></tt> implies the default behavior (<tt class="docutils literal"><span class="pre">128,</span> <span class="pre">256</span></tt>).</p>
+<p>If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-sgpr-clang-amdgpu-num-sgpr">
+<h3><a class="toc-backref" href="#id112">amdgpu_num_sgpr (clang::amdgpu_num_sgpr)</a><a class="headerlink" href="#amdgpu-num-sgpr-clang-amdgpu-num-sgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></tt> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <tt class="docutils literal"><span class="pre">0</span></tt> as
+<tt class="docutils literal"><span class="pre">num_sgpr</span></tt> and/or <tt class="docutils literal"><span class="pre">num_vgpr</span></tt> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <tt class="docutils literal"><span class="pre">amdgpu_waves_per_eu</span></tt> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-vgpr-clang-amdgpu-num-vgpr">
+<h3><a class="toc-backref" href="#id113">amdgpu_num_vgpr (clang::amdgpu_num_vgpr)</a><a class="headerlink" href="#amdgpu-num-vgpr-clang-amdgpu-num-vgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></tt> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <tt class="docutils literal"><span class="pre">0</span></tt> as
+<tt class="docutils literal"><span class="pre">num_sgpr</span></tt> and/or <tt class="docutils literal"><span class="pre">num_vgpr</span></tt> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <tt class="docutils literal"><span class="pre">amdgpu_waves_per_eu</span></tt> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-waves-per-eu-clang-amdgpu-waves-per-eu">
+<h3><a class="toc-backref" href="#id114">amdgpu_waves_per_eu (clang::amdgpu_waves_per_eu)</a><a class="headerlink" href="#amdgpu-waves-per-eu-clang-amdgpu-waves-per-eu" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.</p>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_waves_per_eu(<min>[,</span> <span class="pre"><max>])))</span></tt>
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.</p>
+<p><tt class="docutils literal"><span class="pre"><min></span></tt> parameter specifies the requested minimum number of waves per EU, and
+<em>optional</em> <tt class="docutils literal"><span class="pre"><max></span></tt> parameter specifies the requested maximum number of waves
+per EU (must be greater than <tt class="docutils literal"><span class="pre"><min></span></tt> if specified). If <tt class="docutils literal"><span class="pre"><max></span></tt> is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+<tt class="docutils literal"><span class="pre">0,</span> <span class="pre">0</span></tt> as <tt class="docutils literal"><span class="pre"><min>,</span> <span class="pre"><max></span></tt> implies the default behavior (no limits).</p>
+<p>If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least <tt class="docutils literal"><span class="pre"><min></span></tt> wavefronts and at most
+<tt class="docutils literal"><span class="pre"><max></span></tt> wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.</p>
+<p>This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="consumed-annotation-checking">
+<h2><a class="toc-backref" href="#id115">Consumed Annotation Checking</a><a class="headerlink" href="#consumed-annotation-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although <strong>the implementation
+for these annotations is currently in development and are subject to change.</strong></p>
+<div class="section" id="callable-when-clang-callable-when">
+<h3><a class="toc-backref" href="#id116">callable_when (clang::callable_when)</a><a class="headerlink" href="#callable-when-clang-callable-when" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((callable_when(...)))</span></tt> to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:</p>
+<p><tt class="docutils literal"><span class="pre">__attribute__((callable_when("unconsumed",</span> <span class="pre">"unknown")))</span></tt></p>
+</div>
+<div class="section" id="consumable-clang-consumable">
+<h3><a class="toc-backref" href="#id117">consumable (clang::consumable)</a><a class="headerlink" href="#consumable-clang-consumable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Each <tt class="docutils literal"><span class="pre">class</span></tt> that uses any of the typestate annotations must first be marked
+using the <tt class="docutils literal"><span class="pre">consumable</span></tt> attribute. Failure to do so will result in a warning.</p>
+<p>This attribute accepts a single parameter that must be one of the following:
+<tt class="docutils literal"><span class="pre">unknown</span></tt>, <tt class="docutils literal"><span class="pre">consumed</span></tt>, or <tt class="docutils literal"><span class="pre">unconsumed</span></tt>.</p>
+</div>
+<div class="section" id="param-typestate-clang-param-typestate">
+<h3><a class="toc-backref" href="#id118">param_typestate (clang::param_typestate)</a><a class="headerlink" href="#param-typestate-clang-param-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn’t in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function’s body.</p>
+</div>
+<div class="section" id="return-typestate-clang-return-typestate">
+<h3><a class="toc-backref" href="#id119">return_typestate (clang::return_typestate)</a><a class="headerlink" href="#return-typestate-clang-return-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">return_typestate</span></tt> attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function’s body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.</p>
+<p>When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function’s body is checked to ensure that
+the parameter is in the expected state before returning.</p>
+</div>
+<div class="section" id="set-typestate-clang-set-typestate">
+<h3><a class="toc-backref" href="#id120">set_typestate (clang::set_typestate)</a><a class="headerlink" href="#set-typestate-clang-set-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Annotate methods that transition an object into a new state with
+<tt class="docutils literal"><span class="pre">__attribute__((set_typestate(new_state)))</span></tt>. The new state must be
+unconsumed, consumed, or unknown.</p>
+</div>
+<div class="section" id="test-typestate-clang-test-typestate">
+<h3><a class="toc-backref" href="#id121">test_typestate (clang::test_typestate)</a><a class="headerlink" href="#test-typestate-clang-test-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((test_typestate(tested_state)))</span></tt> to indicate that a method
+returns true if the object is in the specified state..</p>
+</div>
+</div>
+<div class="section" id="type-safety-checking">
+<h2><a class="toc-backref" href="#id122">Type Safety Checking</a><a class="headerlink" href="#type-safety-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes to enable checking type safety properties
+that can’t be enforced by the C type system. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:</p>
+<ul class="simple">
+<li>MPI library implementations, where these attributes enable checking that
+the buffer type matches the passed <tt class="docutils literal"><span class="pre">MPI_Datatype</span></tt>;</li>
+<li>for HDF5 library there is a similar use case to MPI;</li>
+<li>checking types of variadic functions’ arguments for functions like
+<tt class="docutils literal"><span class="pre">fcntl()</span></tt> and <tt class="docutils literal"><span class="pre">ioctl()</span></tt>.</li>
+</ul>
+<p>You can detect support for these attributes with <tt class="docutils literal"><span class="pre">__has_attribute()</span></tt>. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(__has_attribute)</span>
+<span class="cp"># if __has_attribute(argument_with_type_tag) && \</span>
+<span class="cp"> __has_attribute(pointer_with_type_tag) && \</span>
+<span class="cp"> __has_attribute(type_tag_for_datatype)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))</span>
+<span class="cp">/* ... other macros ... */</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if !defined(ATTR_MPI_PWT)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx)</span>
+<span class="cp">#endif</span>
+
+<span class="kt">int</span> <span class="n">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+ <span class="n">ATTR_MPI_PWT</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="section" id="argument-with-type-tag">
+<h3><a class="toc-backref" href="#id123">argument_with_type_tag</a><a class="headerlink" href="#argument-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((argument_with_type_tag(arg_kind,</span> <span class="pre">arg_idx,</span>
+<span class="pre">type_tag_idx)))</span></tt> on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.</p>
+<p>This attribute is primarily useful for checking arguments of variadic functions
+(<tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt> can be used in most non-variadic cases).</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">arg_kind</span></tt> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><tt class="docutils literal"><span class="pre">arg_idx</span></tt> provides the position of a function argument. The expected type of
+this function argument will be determined by the function argument specified
+by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>. In the code example below, “3” means that the type of the
+function’s third argument will be determined by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">type_tag_idx</span></tt> provides the position of a function argument. This function
+argument will be a type tag. The type tag will determine the expected type of
+the argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt>. In the code example below, “2” means
+that the type tag associated with the function’s second argument should agree
+with the type of the argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">fcntl</span><span class="p">(</span><span class="kt">int</span> <span class="n">fd</span><span class="p">,</span> <span class="kt">int</span> <span class="n">cmd</span><span class="p">,</span> <span class="p">...)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">argument_with_type_tag</span><span class="p">(</span><span class="n">fcntl</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's second argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected type of the function's third argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-with-type-tag">
+<h3><a class="toc-backref" href="#id124">pointer_with_type_tag</a><a class="headerlink" href="#pointer-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((pointer_with_type_tag(ptr_kind,</span> <span class="pre">ptr_idx,</span> <span class="pre">type_tag_idx)))</span></tt>
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">ptr_kind</span></tt> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><tt class="docutils literal"><span class="pre">ptr_idx</span></tt> provides the position of a function argument; this function
+argument will have a pointer type. The expected pointee type of this pointer
+type will be determined by the function argument specified by
+<tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>. In the code example below, “1” means that the pointee type
+of the function’s first argument will be determined by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">type_tag_idx</span></tt> provides the position of a function argument; this function
+argument will be a type tag. The type tag will determine the expected pointee
+type of the pointer argument specified by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt>. In the code example
+below, “3” means that the type tag associated with the function’s third
+argument should agree with the pointee type of the pointer argument specified
+by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's 3rd argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected pointee type of the function's 1st argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="type-tag-for-datatype">
+<h3><a class="toc-backref" href="#id125">type_tag_for_datatype</a><a class="headerlink" href="#type-tag-for-datatype" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When declaring a variable, use
+<tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> to create a type tag that
+is tied to the <tt class="docutils literal"><span class="pre">type</span></tt> argument given to the attribute.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">kind</span></tt> is an identifier that should be used when annotating all applicable
+type tags.</li>
+<li><tt class="docutils literal"><span class="pre">type</span></tt> indicates the name of the type.</li>
+</ul>
+</dd>
+</dl>
+<p>Clang supports annotating type tags of two forms.</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><strong>Type tag that is a reference to a declared identifier.</strong>
+Use <tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> when declaring that
+identifier:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_int</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">));</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)</span>
+<span class="c1">// &mpi_datatype_int is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><strong>Type tag that is an integral literal.</strong>
+Declare a <tt class="docutils literal"><span class="pre">static</span> <span class="pre">const</span></tt> variable with an initializer value and attach
+<tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> on that declaration:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MPI_Datatype</span> <span class="n">mpi_datatype_int</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">))</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) 42)</span>
+<span class="c1">// The number 42 is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+<p>The <tt class="docutils literal"><span class="pre">type_tag_for_datatype</span></tt> attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+<tt class="docutils literal"><span class="pre">arg_idx</span></tt> or <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> is compared against the type associated with the type
+tag. (Recall that for the <tt class="docutils literal"><span class="pre">argument_with_type_tag</span></tt> attribute, the type of the
+function argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt> is compared against the type
+associated with the type tag. Also recall that for the <tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt>
+attribute, the pointee type of the function argument specified by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">layout_compatible</span></tt> will cause types to be compared according to
+layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+layout-compatibility rules for two standard-layout struct types and for two
+standard-layout union types). This is useful when creating a type tag
+associated with a struct or union type. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">internal_mpi_double_int</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">d</span><span class="p">;</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_double_int</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">internal_mpi_double_int</span><span class="p">,</span> <span class="n">layout_compatible</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)</span>
+
+<span class="kt">int</span> <span class="n">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// no warning because the</span>
+ <span class="c1">// layout of my_pair is</span>
+ <span class="c1">// compatible with that of</span>
+ <span class="c1">// internal_mpi_double_int</span>
+
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">}</span>
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="o">*</span><span class="n">buffer2</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// warning because the</span>
+ <span class="c1">// layout of my_int_pair</span>
+ <span class="c1">// does not match that of</span>
+ <span class="c1">// internal_mpi_double_int</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">must_be_null</span></tt> specifies that the function argument specified by either
+<tt class="docutils literal"><span class="pre">arg_idx</span></tt> (for the <tt class="docutils literal"><span class="pre">argument_with_type_tag</span></tt> attribute) or <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> (for
+the <tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt> attribute) should be a null pointer constant.
+The second argument to the <tt class="docutils literal"><span class="pre">type_tag_for_datatype</span></tt> attribute is ignored. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_null</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span> <span class="kt">void</span><span class="p">,</span> <span class="n">must_be_null</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)</span>
+<span class="kt">int</span> <span class="n">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DATATYPE_NULL</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// warning: MPI_DATATYPE_NULL</span>
+ <span class="c1">// was specified but buffer</span>
+ <span class="c1">// is not a null pointer</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="opencl-address-spaces">
+<h2><a class="toc-backref" href="#id126">OpenCL Address Spaces</a><a class="headerlink" href="#opencl-address-spaces" title="Permalink to this headline">¶</a></h2>
+<p>The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+__generic(generic), __global(global), __local(local), __private(private),
+__constant(constant).</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">__constant</span> <span class="kt">int</span> <span class="n">c</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="n">__generic</span> <span class="kt">int</span><span class="o">*</span> <span class="nf">foo</span><span class="p">(</span><span class="n">global</span> <span class="kt">int</span><span class="o">*</span> <span class="n">g</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">__local</span> <span class="kt">int</span><span class="o">*</span> <span class="n">l</span><span class="p">;</span>
+ <span class="n">private</span> <span class="kt">int</span> <span class="n">p</span><span class="p">;</span>
+ <span class="p">...</span>
+ <span class="k">return</span> <span class="n">l</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.5.</p>
+<div class="section" id="constant-constant">
+<h3><a class="toc-backref" href="#id127">constant (__constant)</a><a class="headerlink" href="#constant-constant" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.</p>
+</div>
+<div class="section" id="generic-generic">
+<h3><a class="toc-backref" href="#id128">generic (__generic)</a><a class="headerlink" href="#generic-generic" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for ‘__constant’ in OpenCL code which can be used with multiple address
+spaces.</p>
+</div>
+<div class="section" id="global-global">
+<h3><a class="toc-backref" href="#id129">global (__global)</a><a class="headerlink" href="#global-global" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.</p>
+</div>
+<div class="section" id="local-local">
+<h3><a class="toc-backref" href="#id130">local (__local)</a><a class="headerlink" href="#local-local" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.</p>
+</div>
+<div class="section" id="private-private">
+<h3><a class="toc-backref" href="#id131">private (__private)</a><a class="headerlink" href="#private-private" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.</p>
+</div>
+</div>
+<div class="section" id="nullability-attributes">
+<h2><a class="toc-backref" href="#id132">Nullability Attributes</a><a class="headerlink" href="#nullability-attributes" title="Permalink to this headline">¶</a></h2>
+<p>Whether a particular pointer may be “null” is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the <tt class="docutils literal"><span class="pre">nonnull</span></tt> and <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (<tt class="docutils literal"><span class="pre">_Nullable</span></tt>) or cannot be null (<tt class="docutils literal"><span class="pre">_Nonnull</span></tt>).</p>
+<p>The nullability (type) qualifiers express whether a value of a given pointer type can be null (the <tt class="docutils literal"><span class="pre">_Nullable</span></tt> qualifier), doesn’t have a defined meaning for null (the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> qualifier), or for which the purpose of null is unclear (the <tt class="docutils literal"><span class="pre">_Null_unspecified</span></tt> qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the <tt class="docutils literal"><span class="pre">nonnull</span></tt> and <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="c1">// No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).</span>
+<span class="kt">int</span> <span class="nf">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">*</span><span class="n">ptr</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="c1">// 'ptr' may be null.</span>
+<span class="kt">int</span> <span class="nf">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">ptr</span> <span class="o">?</span> <span class="o">*</span><span class="n">ptr</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="c1">// A nullable pointer to non-null pointers to const characters.</span>
+<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">join_strings</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">strings</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">n</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:</p>
+<blockquote>
+<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">NSView</span> : <span class="nc">NSResponder</span>
+ <span class="o">-</span> <span class="p">(</span><span class="n">nullable</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="nl">ancestorSharedWithView:</span><span class="p">(</span><span class="n">nonnull</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="n">aView</span><span class="p">;</span>
+ <span class="k">@property</span> <span class="p">(</span><span class="n">assign</span><span class="p">,</span> <span class="n">nullable</span><span class="p">)</span> <span class="n">NSView</span> <span class="o">*</span><span class="n">superview</span><span class="p">;</span>
+ <span class="k">@property</span> <span class="p">(</span><span class="n">readonly</span><span class="p">,</span> <span class="n">nonnull</span><span class="p">)</span> <span class="n">NSArray</span> <span class="o">*</span><span class="n">subviews</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="nonnull">
+<h3><a class="toc-backref" href="#id133">_Nonnull</a><a class="headerlink" href="#nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> nullability qualifier indicates that null is not a meaningful value for a value of the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> pointer type. For example, given a declaration such as:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <tt class="docutils literal"><span class="pre">fetch</span></tt> should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to <tt class="docutils literal"><span class="pre">fetch</span></tt>. Note that, unlike the declaration attribute <tt class="docutils literal"><span class="pre">nonnull</span></tt>, the presence of <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> does not imply that passing null is undefined behavior: <tt class="docutils literal"><span class="pre">fetch</span></tt> is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.</p>
+</div>
+<div class="section" id="null-unspecified">
+<h3><a class="toc-backref" href="#id134">_Null_unspecified</a><a class="headerlink" href="#null-unspecified" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Null_unspecified</span></tt> nullability qualifier indicates that neither the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> nor <tt class="docutils literal"><span class="pre">_Nullable</span></tt> qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.</p>
+</div>
+<div class="section" id="nullable">
+<h3><a class="toc-backref" href="#id135">_Nullable</a><a class="headerlink" href="#nullable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Nullable</span></tt> nullability qualifier indicates that a value of the <tt class="docutils literal"><span class="pre">_Nullable</span></tt> pointer type can be null. For example, given:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <tt class="docutils literal"><span class="pre">fetch_or_zero</span></tt> can provide null.</p>
+</div>
+<div class="section" id="nonnull-gnu-nonnull">
+<h3><a class="toc-backref" href="#id136">nonnull (gnu::nonnull)</a><a class="headerlink" href="#nonnull-gnu-nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that some function parameters must not be null, and can be used in several different ways. It’s original usage (<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes">from GCC</a>) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Here, the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Clang also allows the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span>
+ <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Note that the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.</p>
+</div>
+<div class="section" id="returns-nonnull-gnu-returns-nonnull">
+<h3><a class="toc-backref" href="#id137">returns_nonnull (gnu::returns_nonnull)</a><a class="headerlink" href="#returns-nonnull-gnu-returns-nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+<th class="head">Pragma clang attribute</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system <tt class="docutils literal"><span class="pre">malloc</span></tt> might be defined to terminate a process when memory is not available rather than returning a null pointer:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">malloc</span> <span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">returns_nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>The <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ClangCommandLineReference.html">Clang command line argument reference</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list