doc/ext_jit.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <title>jit.* Library</title>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <meta name="Copyright" content="Copyright (C) 2005-2018">
   7 <meta name="Language" content="en">
   8 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
   9 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
  10 </head>
  11 <body>
  12 <div id="site">
  13 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  14 </div>
  15 <div id="head">
  16 <h1><tt>jit.*</tt> Library</h1>
  17 </div>
  18 <div id="nav">
  19 <ul><li>
  20 <a href="luajit.html">LuaJIT</a>
  21 <ul><li>
  22 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  23 </li><li>
  24 <a href="install.html">Installation</a>
  25 </li><li>
  26 <a href="running.html">Running</a>
  27 </li></ul>
  28 </li><li>
  29 <a href="extensions.html">Extensions</a>
  30 <ul><li>
  31 <a href="ext_ffi.html">FFI Library</a>
  32 <ul><li>
  33 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  34 </li><li>
  35 <a href="ext_ffi_api.html">ffi.* API</a>
  36 </li><li>
  37 <a href="ext_ffi_semantics.html">FFI Semantics</a>
  38 </li></ul>
  39 </li><li>
  40 <a class="current" href="ext_jit.html">jit.* Library</a>
  41 </li><li>
  42 <a href="ext_c_api.html">Lua/C API</a>
  43 </li></ul>
  44 </li><li>
  45 <a href="status.html">Status</a>
  46 <ul><li>
  47 <a href="changes.html">Changes</a>
  48 </li></ul>
  49 </li><li>
  50 <a href="faq.html">FAQ</a>
  51 </li><li>
  52 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  53 </li><li>
  54 <a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
  55 </li><li>
  56 <a href="http://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
  57 </li></ul>
  58 </div>
  59 <div id="main">
  60 <p>
  61 The functions in this built-in module control the behavior of the JIT
  62 compiler engine. Note that JIT-compilation is fully automatic &mdash;
  63 you probably won't need to use any of the following functions unless
  64 you have special needs.
  65 </p>
  66
  67 <h3 id="jit_onoff"><tt>jit.on()<br>
  68 jit.off()</tt></h3>
  69 <p>
  70 Turns the whole JIT compiler on (default) or off.
  71 </p>
  72 <p>
  73 These functions are typically used with the command line options
  74 <tt>-j on</tt> or <tt>-j off</tt>.
  75 </p>
  76
  77 <h3 id="jit_flush"><tt>jit.flush()</tt></h3>
  78 <p>
  79 Flushes the whole cache of compiled code.
  80 </p>
  81
  82 <h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
  83 jit.off(func|true [,true|false])<br>
  84 jit.flush(func|true [,true|false])</tt></h3>
  85 <p>
  86 <tt>jit.on</tt> enables JIT compilation for a Lua function (this is
  87 the default).
  88 </p>
  89 <p>
  90 <tt>jit.off</tt> disables JIT compilation for a Lua function and
  91 flushes any already compiled code from the code cache.
  92 </p>
  93 <p>
  94 <tt>jit.flush</tt> flushes the code, but doesn't affect the
  95 enable/disable status.
  96 </p>
  97 <p>
  98 The current function, i.e. the Lua function calling this library
  99 function, can also be specified by passing <tt>true</tt> as the first
 100 argument.
 101 </p>
 102 <p>
 103 If the second argument is <tt>true</tt>, JIT compilation is also
 104 enabled, disabled or flushed recursively for all sub-functions of a
 105 function. With <tt>false</tt> only the sub-functions are affected.
 106 </p>
 107 <p>
 108 The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
 109 which is checked when the function is about to be compiled. They do
 110 not trigger immediate compilation.
 111 </p>
 112 <p>
 113 Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
 114 of a module to turn off JIT compilation for the whole module for
 115 debugging purposes.
 116 </p>
 117
 118 <h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
 119 <p>
 120 Flushes the root trace, specified by its number, and all of its side
 121 traces from the cache. The code for the trace will be retained as long
 122 as there are any other traces which link to it.
 123 </p>
 124
 125 <h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
 126 <p>
 127 Returns the current status of the JIT compiler. The first result is
 128 either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
 129 on or off. The remaining results are strings for CPU-specific features
 130 and enabled optimizations.
 131 </p>
 132
 133 <h3 id="jit_version"><tt>jit.version</tt></h3>
 134 <p>
 135 Contains the LuaJIT version string.
 136 </p>
 137
 138 <h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
 139 <p>
 140 Contains the version number of the LuaJIT core. Version xx.yy.zz
 141 is represented by the decimal number xxyyzz.
 142 </p>
 143
 144 <h3 id="jit_os"><tt>jit.os</tt></h3>
 145 <p>
 146 Contains the target OS name:
 147 "Windows", "Linux", "OSX", "BSD", "POSIX" or "Other".
 148 </p>
 149
 150 <h3 id="jit_arch"><tt>jit.arch</tt></h3>
 151 <p>
 152 Contains the target architecture name:
 153 "x86", "x64", "arm", "ppc", "ppcspe", or "mips".
 154 </p>
 155
 156 <h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
 157 <p>
 158 This sub-module provides the backend for the <tt>-O</tt> command line
 159 option.
 160 </p>
 161 <p>
 162 You can also use it programmatically, e.g.:
 163 </p>
 164 <pre class="code">
 165 jit.opt.start(2) -- same as -O2
 166 jit.opt.start("-dce")
 167 jit.opt.start("hotloop=10", "hotexit=2")
 168 </pre>
 169 <p>
 170 Unlike in LuaJIT 1.x, the module is built-in and
 171 <b>optimization is turned on by default!</b>
 172 It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
 173 which was one of the ways to enable optimization.
 174 </p>
 175
 176 <h2 id="jit_util"><tt>jit.util.*</tt> &mdash; JIT compiler introspection</h2>
 177 <p>
 178 This sub-module holds functions to introspect the bytecode, generated
 179 traces, the IR and the generated machine code. The functionality
 180 provided by this module is still in flux and therefore undocumented.
 181 </p>
 182 <p>
 183 The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
 184 extensive use of these functions. Please check out their source code,
 185 if you want to know more.
 186 </p>
 187 <br class="flush">
 188 </div>
 189 <div id="foot">
 190 <hr class="hide">
 191 Copyright &copy; 2005-2018
 192 <span class="noprint">
 193 &middot;
 194 <a href="contact.html">Contact</a>
 195 </span>
 196 </div>
 197 </body>
 198 </html>