diff options
Diffstat (limited to 'libs/luajit-cmake/luajit/doc/ext_c_api.html')
| -rw-r--r-- | libs/luajit-cmake/luajit/doc/ext_c_api.html | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/libs/luajit-cmake/luajit/doc/ext_c_api.html b/libs/luajit-cmake/luajit/doc/ext_c_api.html new file mode 100644 index 0000000..151d20b --- /dev/null +++ b/libs/luajit-cmake/luajit/doc/ext_c_api.html @@ -0,0 +1,183 @@ +<!DOCTYPE html> +<html> +<head> +<title>Lua/C API Extensions</title> +<meta charset="utf-8"> +<meta name="Copyright" content="Copyright (C) 2005-2022"> +<meta name="Language" content="en"> +<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> +<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> +</head> +<body> +<div id="site"> +<a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> +</div> +<div id="head"> +<h1>Lua/C API Extensions</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="https://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><li> +<a href="install.html">Installation</a> +</li><li> +<a href="running.html">Running</a> +</li></ul> +</li><li> +<a href="extensions.html">Extensions</a> +<ul><li> +<a href="ext_ffi.html">FFI Library</a> +<ul><li> +<a href="ext_ffi_tutorial.html">FFI Tutorial</a> +</li><li> +<a href="ext_ffi_api.html">ffi.* API</a> +</li><li> +<a href="ext_ffi_semantics.html">FFI Semantics</a> +</li></ul> +</li><li> +<a href="ext_buffer.html">String Buffers</a> +</li><li> +<a href="ext_jit.html">jit.* Library</a> +</li><li> +<a class="current" href="ext_c_api.html">Lua/C API</a> +</li><li> +<a href="ext_profiler.html">Profiler</a> +</li></ul> +</li><li> +<a href="status.html">Status</a> +</li><li> +<a href="faq.html">FAQ</a> +</li><li> +<a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include +directory must be in the compiler search path (<tt>-I<i>path</i></tt>) +to be able to include the required header for C code: +</p> +<pre class="code"> +#include "luajit.h" +</pre> +<p> +Or for C++ code: +</p> +<pre class="code"> +#include "lua.hpp" +</pre> + +<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt> +— Control VM</h2> +<p> +This is a C API extension to allow control of the VM from C code. The +full prototype of <tt>LuaJIT_setmode</tt> is: +</p> +<pre class="code"> +LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); +</pre> +<p> +The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>). +The second argument is either <tt>0</tt> or a stack index (similar to the +other Lua/C API functions). +</p> +<p> +The third argument specifies the mode, which is 'or'ed with a flag. +The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature off, +<tt>LUAJIT_MODE_ON</tt> to turn a feature on, or +<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code. +</p> +<p> +The following modes are defined: +</p> + +<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3> +<p> +Turn the whole JIT compiler on or off or flush the whole cache of compiled code. +</p> + +<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br> +<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br> +<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3> +<p> +This sets the mode for the function at the stack index <tt>idx</tt> or +the parent of the calling function (<tt>idx = 0</tt>). It either +enables JIT compilation for a function, disables it and flushes any +already compiled code, or only flushes already compiled code. This +applies recursively to all sub-functions of the function with +<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with +<tt>LUAJIT_MODE_ALLSUBFUNC</tt>. +</p> + +<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br> + LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3> +<p> +Flushes the specified root trace and all of its side traces from the cache. +The code for the trace will be retained as long as there are any other +traces which link to it. +</p> + +<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3> +<p> +This mode defines a wrapper function for calls to C functions. If +called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt> +must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper +function. From now on, all C functions are called through the wrapper +function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned +off and all C functions are directly called. +</p> +<p> +The wrapper function can be used for debugging purposes or to catch +and convert foreign exceptions. But please read the section on +<a href="extensions.html#exceptions">C++ exception interoperability</a> +first. Recommended usage can be seen in this C++ code excerpt: +</p> +<pre class="code"> +#include <exception> +#include "lua.hpp" + +// Catch C++ exceptions and convert them to Lua error messages. +// Customize as needed for your own exception classes. +static int wrap_exceptions(lua_State *L, lua_CFunction f) +{ + try { + return f(L); // Call wrapped function and return result. + } catch (const char *s) { // Catch and convert exceptions. + lua_pushstring(L, s); + } catch (std::exception& e) { + lua_pushstring(L, e.what()); + } catch (...) { + lua_pushliteral(L, "caught (...)"); + } + return lua_error(L); // Rethrow as a Lua error. +} + +static int myinit(lua_State *L) +{ + ... + // Define wrapper function and enable it. + lua_pushlightuserdata(L, (void *)wrap_exceptions); + luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON); + lua_pop(L, 1); + ... +} +</pre> +<p> +Note that you can only define <b>a single global wrapper function</b>, +so be careful when using this mechanism from multiple C++ modules. +Also note that this mechanism is not without overhead. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2022 +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> |