summaryrefslogtreecommitdiff
path: root/doc/ext_c_api.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ext_c_api.html')
-rw-r--r--doc/ext_c_api.html174
1 files changed, 174 insertions, 0 deletions
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html
new file mode 100644
index 00000000..1418b2a9
--- /dev/null
+++ b/doc/ext_c_api.html
@@ -0,0 +1,174 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Lua/C API Extensions</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-2010, 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>Lua/C API Extensions</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_jit.html">jit.* Library</a>
31</li><li>
32<a class="current" href="ext_c_api.html">Lua/C API</a>
33</li></ul>
34</li><li>
35<a href="status.html">Status</a>
36<ul><li>
37<a href="changes.html">Changes</a>
38</li></ul>
39</li><li>
40<a href="faq.html">FAQ</a>
41</li><li>
42<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
43</li><li>
44<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
45</li></ul>
46</div>
47<div id="main">
48<p>
49LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
50directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
51to be able to include the required header for C code:
52</p>
53<pre class="code">
54#include "luajit.h"
55</pre>
56<p>
57Or for C++ code:
58</p>
59<pre class="code">
60#include "lua.hpp"
61</pre>
62
63<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
64&mdash; Control VM</h2>
65<p>
66This is a C API extension to allow control of the VM from C code. The
67full prototype of <tt>LuaJIT_setmode</tt> is:
68</p>
69<pre class="code">
70LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
71</pre>
72<p>
73The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
74The second argument is either <tt>0</tt> or a stack index (similar to the
75other Lua/C API functions).
76</p>
77<p>
78The third argument specifies the mode, which is 'or'ed with a flag.
79The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
80<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
81<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
82</p>
83<p>
84The following modes are defined:
85</p>
86
87<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
88<p>
89Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
90</p>
91
92<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
93<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
94<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
95<p>
96This sets the mode for the function at the stack index <tt>idx</tt> or
97the parent of the calling function (<tt>idx = 0</tt>). It either
98enables JIT compilation for a function, disables it and flushes any
99already compiled code or only flushes already compiled code. This
100applies recursively to all sub-functions of the function with
101<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
102<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
103</p>
104
105<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
106&nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
107<p>
108Flushes the specified root trace and all of its side traces from the cache.
109The code for the trace will be retained as long as there are any other
110traces which link to it.
111</p>
112
113<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
114<p>
115This mode defines a wrapper function for calls to C functions. If
116called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
117must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
118function. From now on all C functions are called through the wrapper
119function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
120off and all C functions are directly called.
121</p>
122<p>
123The wrapper function can be used for debugging purposes or to catch
124and convert foreign exceptions. But please read the section on
125<a href="extensions.html#exceptions">C++&nbsp;exception interoperability</a>
126first. Recommended usage can be seen in this C++ code excerpt:
127</p>
128<pre class="code">
129#include &lt;exception&gt;
130#include "lua.hpp"
131
132// Catch C++ exceptions and convert them to Lua error messages.
133// Customize as needed for your own exception classes.
134static int wrap_exceptions(lua_State *L, lua_CFunction f)
135{
136 try {
137 return f(L); // Call wrapped function and return result.
138 } catch (const char *s) { // Catch and convert exceptions.
139 lua_pushstring(L, s);
140 } catch (std::exception& e) {
141 lua_pushstring(L, e.what());
142 } catch (...) {
143 lua_pushliteral(L, "caught (...)");
144 }
145 return lua_error(L); // Rethrow as a Lua error.
146}
147
148static int myinit(lua_State *L)
149{
150 ...
151 // Define wrapper function and enable it.
152 lua_pushlightuserdata(L, (void *)wrap_exceptions);
153 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
154 lua_pop(L, 1);
155 ...
156}
157</pre>
158<p>
159Note that you can only define <b>a single global wrapper function</b>,
160so be careful when using this mechanism from multiple C++ modules.
161Also note that this mechanism is not without overhead.
162</p>
163<br class="flush">
164</div>
165<div id="foot">
166<hr class="hide">
167Copyright &copy; 2005-2010 Mike Pall
168<span class="noprint">
169&middot;
170<a href="contact.html">Contact</a>
171</span>
172</div>
173</body>
174</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-12 22:38:59 +0000