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