aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/luajit-2.0/doc/ext_c_api.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/luajit-2.0/doc/ext_c_api.html')
-rw-r--r--libraries/luajit-2.0/doc/ext_c_api.html183
1 files changed, 183 insertions, 0 deletions
diff --git a/libraries/luajit-2.0/doc/ext_c_api.html b/libraries/luajit-2.0/doc/ext_c_api.html
new file mode 100644
index 0000000..35e2234
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_c_api.html
@@ -0,0 +1,183 @@
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-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>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_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 href="ext_jit.html">jit.* Library</a>
40</li><li>
41<a class="current" 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>
58LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
59directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
60to be able to include the required header for C code:
61</p>
62<pre class="code">
63#include "luajit.h"
64</pre>
65<p>
66Or 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>
75This is a C API extension to allow control of the VM from C code. The
76full prototype of <tt>LuaJIT_setmode</tt> is:
77</p>
78<pre class="code">
79LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
80</pre>
81<p>
82The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
83The second argument is either <tt>0</tt> or a stack index (similar to the
84other Lua/C API functions).
85</p>
86<p>
87The third argument specifies the mode, which is 'or'ed with a flag.
88The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
89<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
90<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
91</p>
92<p>
93The 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>
98Turn 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>
105This sets the mode for the function at the stack index <tt>idx</tt> or
106the parent of the calling function (<tt>idx = 0</tt>). It either
107enables JIT compilation for a function, disables it and flushes any
108already compiled code or only flushes already compiled code. This
109applies 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>
117Flushes the specified root trace and all of its side traces from the cache.
118The code for the trace will be retained as long as there are any other
119traces 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>
124This mode defines a wrapper function for calls to C functions. If
125called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
126must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
127function. From now on all C functions are called through the wrapper
128function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
129off and all C functions are directly called.
130</p>
131<p>
132The wrapper function can be used for debugging purposes or to catch
133and convert foreign exceptions. But please read the section on
134<a href="extensions.html#exceptions">C++&nbsp;exception interoperability</a>
135first. 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.
143static 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
157static 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>
168Note that you can only define <b>a single global wrapper function</b>,
169so be careful when using this mechanism from multiple C++ modules.
170Also note that this mechanism is not without overhead.
171</p>
172<br class="flush">
173</div>
174<div id="foot">
175<hr class="hide">
176Copyright &copy; 2005-2011 Mike Pall
177<span class="noprint">
178&middot;
179<a href="contact.html">Contact</a>
180</span>
181</div>
182</body>
183</html>
generated by cgit v1.1 at 2024-12-26 03:36:42 +0000