Mercurial

comparison third_party/luajit/doc/ext_c_api.html @ 178:94705b5986b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added WRK and luajit for load testing.
author MrJuneJune <me@mrjunejune.com>
date Thu, 22 Jan 2026 20:10:30 -0800
parents
children
comparison
equal deleted inserted replaced
177:24fe8ff94056 178:94705b5986b3
1 <!DOCTYPE html>
2 <html>
3 <head>
4 <title>Lua/C API Extensions</title>
5 <meta charset="utf-8">
6 <meta name="Copyright" content="Copyright (C) 2005-2023">
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="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
14 </div>
15 <div id="head">
16 <h1>Lua/C API Extensions</h1>
17 </div>
18 <div id="nav">
19 <ul><li>
20 <a href="luajit.html">LuaJIT</a>
21 <ul><li>
22 <a href="https://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 href="ext_buffer.html">String Buffers</a>
41 </li><li>
42 <a href="ext_jit.html">jit.* Library</a>
43 </li><li>
44 <a class="current" href="ext_c_api.html">Lua/C API</a>
45 </li><li>
46 <a href="ext_profiler.html">Profiler</a>
47 </li></ul>
48 </li><li>
49 <a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
50 </li><li>
51 <a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
52 </li><li>
53 <a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
54 </li></ul>
55 </div>
56 <div id="main">
57 <p>
58 LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
59 directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
60 to be able to include the required header for C code:
61 </p>
62 <pre class="code">
63 #include "luajit.h"
64 </pre>
65 <p>
66 Or for C++ code:
67 </p>
68 <pre class="code">
69 #include "lua.hpp"
70 </pre>
71
72 <h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
73 &mdash; Control VM</h2>
74 <p>
75 This is a C API extension to allow control of the VM from C code. The
76 full prototype of <tt>LuaJIT_setmode</tt> is:
77 </p>
78 <pre class="code">
79 LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
80 </pre>
81 <p>
82 The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
83 The second argument is either <tt>0</tt> or a stack index (similar to the
84 other Lua/C API functions).
85 </p>
86 <p>
87 The third argument specifies the mode, which is 'or'ed with a flag.
88 The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature off,
89 <tt>LUAJIT_MODE_ON</tt> to turn a feature on, or
90 <tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
91 </p>
92 <p>
93 The following modes are defined:
94 </p>
95
96 <h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
97 <p>
98 Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
99 </p>
100
101 <h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
102 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
103 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
104 <p>
105 This sets the mode for the function at the stack index <tt>idx</tt> or
106 the parent of the calling function (<tt>idx = 0</tt>). It either
107 enables JIT compilation for a function, disables it and flushes any
108 already compiled code, or only flushes already compiled code. This
109 applies recursively to all sub-functions of the function with
110 <tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
111 <tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
112 </p>
113
114 <h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
115 &nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
116 <p>
117 Flushes the specified root trace and all of its side traces from the cache.
118 The code for the trace will be retained as long as there are any other
119 traces which link to it.
120 </p>
121
122 <h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
123 <p>
124 This mode defines a wrapper function for calls to C functions. If
125 called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
126 must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
127 function. From now on, all C functions are called through the wrapper
128 function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
129 off and all C functions are directly called.
130 </p>
131 <p>
132 The wrapper function can be used for debugging purposes or to catch
133 and convert foreign exceptions. But please read the section on
134 <a href="extensions.html#exceptions">C++&nbsp;exception interoperability</a>
135 first. Recommended usage can be seen in this C++ code excerpt:
136 </p>
137 <pre class="code">
138 #include &lt;exception&gt;
139 #include "lua.hpp"
140
141 // Catch C++ exceptions and convert them to Lua error messages.
142 // Customize as needed for your own exception classes.
143 static int wrap_exceptions(lua_State *L, lua_CFunction f)
144 {
145 try {
146 return f(L); // Call wrapped function and return result.
147 } catch (const char *s) { // Catch and convert exceptions.
148 lua_pushstring(L, s);
149 } catch (std::exception& e) {
150 lua_pushstring(L, e.what());
151 } catch (...) {
152 lua_pushliteral(L, "caught (...)");
153 }
154 return lua_error(L); // Rethrow as a Lua error.
155 }
156
157 static int myinit(lua_State *L)
158 {
159 ...
160 // Define wrapper function and enable it.
161 lua_pushlightuserdata(L, (void *)wrap_exceptions);
162 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
163 lua_pop(L, 1);
164 ...
165 }
166 </pre>
167 <p>
168 Note that you can only define <b>a single global wrapper function</b>,
169 so be careful when using this mechanism from multiple C++ modules.
170 Also note that this mechanism is not without overhead.
171 </p>
172 <br class="flush">
173 </div>
174 <div id="foot">
175 <hr class="hide">
176 Copyright &copy; 2005-2023
177 <span class="noprint">
178 &middot;
179 <a href="contact.html">Contact</a>
180 </span>
181 </div>
182 </body>
183 </html>