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