From 8d8a2529ad8c266112c4c1a82db327fb3a4d3f7b Mon Sep 17 00:00:00 2001 From: "Yichun Zhang (agentzh)" Date: Wed, 29 Jun 2016 13:26:43 -0700 Subject: [PATCH] feature: added the official LuaJIT documentation from LuaJIT 2.1 to our restydoc indexes. --- .gitignore | 1 + doc/LuaJIT-2.1/README.pod | 201 ++++ doc/LuaJIT-2.1/contact.pod | 83 ++ doc/LuaJIT-2.1/ext_c_api.pod | 176 ++++ doc/LuaJIT-2.1/ext_ffi.pod | 285 ++++++ doc/LuaJIT-2.1/ext_ffi_api.pod | 503 ++++++++++ doc/LuaJIT-2.1/ext_ffi_semantics.pod | 1387 ++++++++++++++++++++++++++ doc/LuaJIT-2.1/ext_ffi_tutorial.pod | 640 ++++++++++++ doc/LuaJIT-2.1/ext_jit.pod | 182 ++++ doc/LuaJIT-2.1/ext_profiler.pod | 358 +++++++ doc/LuaJIT-2.1/extensions.pod | 453 +++++++++ doc/LuaJIT-2.1/faq.pod | 224 +++++ doc/LuaJIT-2.1/install.pod | 698 +++++++++++++ doc/LuaJIT-2.1/running.pod | 421 ++++++++ doc/LuaJIT-2.1/status.pod | 103 ++ util/mirror-tarballs | 5 +- 16 files changed, 5719 insertions(+), 1 deletion(-) create mode 100644 doc/LuaJIT-2.1/README.pod create mode 100644 doc/LuaJIT-2.1/contact.pod create mode 100644 doc/LuaJIT-2.1/ext_c_api.pod create mode 100644 doc/LuaJIT-2.1/ext_ffi.pod create mode 100644 doc/LuaJIT-2.1/ext_ffi_api.pod create mode 100644 doc/LuaJIT-2.1/ext_ffi_semantics.pod create mode 100644 doc/LuaJIT-2.1/ext_ffi_tutorial.pod create mode 100644 doc/LuaJIT-2.1/ext_jit.pod create mode 100644 doc/LuaJIT-2.1/ext_profiler.pod create mode 100644 doc/LuaJIT-2.1/extensions.pod create mode 100644 doc/LuaJIT-2.1/faq.pod create mode 100644 doc/LuaJIT-2.1/install.pod create mode 100644 doc/LuaJIT-2.1/running.pod create mode 100644 doc/LuaJIT-2.1/status.pod diff --git a/.gitignore b/.gitignore index 909a7b0..db4d599 100644 --- a/.gitignore +++ b/.gitignore @@ -74,3 +74,4 @@ upload upload-win32 html_out/ TODO +doc/LuaJIT-2.1/changes.pod diff --git a/doc/LuaJIT-2.1/README.pod b/doc/LuaJIT-2.1/README.pod new file mode 100644 index 0000000..d077b8b --- /dev/null +++ b/doc/LuaJIT-2.1/README.pod @@ -0,0 +1,201 @@ +=pod + +LuaJIT + +=head1 LuaJIT + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT is a B (JIT) for the E Lua +programming language. Lua is a powerful, dynamic and light-weight +programming language. It may be embedded or used as a general-purpose, +stand-alone language. + +LuaJIT is Copyright E 2005-2016 Mike Pall, released under the +E MIT open source license. + +=head2 Compatibility + +Windows + +Linux + +BSD + +OSX + +POSIX + +Embedded + +Android + +iOS + +PS3 + +PS4 + +PS Vita + +Xbox 360 + +Xbox One + +GCC + +Clang + +LLVM + +MSVC + +x86 + +x64 + +ARM + +ARM64 + +PPC + +MIPS32 + +MIPS64 + +Lua 5.1 + +API+ABI + ++ JIT + ++ BitOp + ++ FFI + +Drop-in + +DLL/.so + +=head2 Overview + +3x + +- 100x + +115 KB + +VM + +90 KB + +JIT + +63 KLOC + +C + +24 KLOC + +ASM + +11 KLOC + +Lua + +LuaJIT has been successfully used as a B in +games, appliances, network and graphics apps, numerical simulations, +trading platforms and many other specialty applications. It scales from +embedded devices, smartphones, desktops up to server farms. It combines +high flexibility with E high performance and an unmatched +B. + +LuaJIT has been in continuous development since 2005. It's widely +considered to be B. It has outperformed other dynamic languages on many +cross-language benchmarks since its first release E often by a +substantial margin. + +For B, the whole VM has been rewritten from the ground up +and relentlessly optimized for performance. It combines a B, written in assembler, with a B. + +An innovative B is integrated with advanced, SSA-based +optimizations and highly tuned code generation backends. A substantial +reduction of the overhead associated with dynamic languages allows it +to break into the performance range traditionally reserved for offline, +static language compilers. + +=head2 More ... + +Please select a sub-topic in the navigation bar to learn more about +LuaJIT. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file luajit.html +# 8082 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/contact.pod b/doc/LuaJIT-2.1/contact.pod new file mode 100644 index 0000000..cf3590b --- /dev/null +++ b/doc/LuaJIT-2.1/contact.pod @@ -0,0 +1,83 @@ +=pod + +LuaJIT + +=head1 Contact + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +Please send general questions to the E LuaJIT mailing list. +You can also send any questions you have directly to me: + +Contact info in image + +=head2 Copyright + +All documentation is Copyright E 2005-2016 Mike Pall. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file contact.html +# 2813 bytes of input +#Wed Jun 29 13:18:14 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/ext_c_api.pod b/doc/LuaJIT-2.1/ext_c_api.pod new file mode 100644 index 0000000..9f1e4db --- /dev/null +++ b/doc/LuaJIT-2.1/ext_c_api.pod @@ -0,0 +1,176 @@ +=pod + +LuaJIT + +=head1 Lua/C API Extensions + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT +include directory must be in the compiler search path (C<-II>) to +be able to include the required header for C code: + + #include "luajit.h" + +Or for C++ code: + + #include "lua.hpp" + +=head2 C E Control VM + +This is a C API extension to allow control of the VM from C code. The +full prototype of C is: + + LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); + +The returned status is either success (C<1>) or failure (C<0>). The +second argument is either C<0> or a stack index (similar to the other +Lua/C API functions). + +The third argument specifies the mode, which is 'or'ed with a flag. The +flag can be C to turn a feature on, C +to turn a feature off, or C to flush cached code. + +The following modes are defined: + +=head2 C + +Turn the whole JIT compiler on or off or flush the whole cache of +compiled code. + +=head2 C + +C + +C + +This sets the mode for the function at the stack index C or the +parent of the calling function (C). 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 +C or only to the sub-functions with +C. + +=head2 luaJIT_setmode(L, trace, + +LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH) + +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. + +=head2 C + +This mode defines a wrapper function for calls to C functions. If +called with C, the stack index at C must be a +C object holding a pointer to the wrapper function. From +now on all C functions are called through the wrapper function. If +called with C this mode is turned off and all C +functions are directly called. + +The wrapper function can be used for debugging purposes or to catch and +convert foreign exceptions. But please read the section on C++ +exception interoperability first. Recommended usage can be seen in this +C++ code excerpt: + + #include + #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); + ... + } + +Note that you can only define B, so +be careful when using this mechanism from multiple C++ modules. Also +note that this mechanism is not without overhead. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_c_api.html +# 6042 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render +# Deleting phrasal "code" element (`tt_18) because it has super-phrasal elements (`br_3) as children. diff --git a/doc/LuaJIT-2.1/ext_ffi.pod b/doc/LuaJIT-2.1/ext_ffi.pod new file mode 100644 index 0000000..f70973c --- /dev/null +++ b/doc/LuaJIT-2.1/ext_ffi.pod @@ -0,0 +1,285 @@ +=pod + +LuaJIT + +=head1 FFI Library + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +The FFI library allows B and B from pure Lua code. + +The FFI library largely obviates the need to write tedious manual Lua/C +bindings in C. No need to learn a separate binding language E +B These can be cut-n-pasted from C +header files or reference manuals. It's up to the task of binding large +libraries without the need for dealing with fragile binding generators. + +The FFI library is tightly integrated into LuaJIT (it's not available +as a separate module). The code generated by the JIT-compiler for +accesses to C data structures from Lua code is on par with the code a C +compiler would generate. Calls to C functions can be inlined in +JIT-compiled code, unlike calls to functions bound via the classic +Lua/C API. + +This page gives a short introduction to the usage of the FFI library. +I + +=head2 Motivating Example: Calling External C Functions + +It's really easy to call an external C library function: + + ① + ② + + + ③local ffi = require("ffi") + ffi.cdef[[ + int printf(const char *fmt, ...); + ]] + ffi.C.printf("Hello %s!", "world") + +So, let's pick that apart: + +Load the FFI library. + +Add a C declaration for the function. The part inside the +double-brackets (in green) is just standard C syntax. + +Call the named C function E Yes, it's that simple! + +Actually, what goes on behind the scenes is far from simple: makes use +of the standard C library namespace C. Indexing this namespace +with a symbol name (C<"printf">) automatically binds it to the standard +C library. The result is a special kind of object which, when called, +runs the C function. The arguments passed to this function are +automatically converted from Lua objects to the corresponding C types. + +Ok, so maybe the use of C wasn't such a spectacular example. +You could have done that with C and C, +too. But you get the idea ... + +So here's something to pop up a message box on Windows: + + local ffi = require("ffi") + ffi.cdef[[ + int MessageBoxA(void *w, const char *txt, const char *cap, int type); + ]] + ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0) + +Bing! Again, that was far too easy, no? + +Compare this with the effort required to bind that function using the +classic Lua/C API: create an extra C file, add a C function that +retrieves and checks the argument types passed from Lua and calls the +actual C function, add a list of module functions and their names, add +a C function and register all module functions, compile and +link it into a shared library (DLL), move it to the proper path, add +Lua code that loads the module aaaand ... finally call the binding +function. Phew! + +=head2 Motivating Example: Using C Data Structures + +The FFI library allows you to create and access C data structures. Of +course the main use for this is for interfacing with C functions. But +they can be used stand-alone, too. + +Lua is built upon high-level data types. They are flexible, extensible +and dynamic. That's why we all love Lua so much. Alas, this can be +inefficient for certain tasks, where you'd really want a low-level data +type. E.g. a large array of a fixed structure needs to be implemented +with a big table holding lots of tiny tables. This imposes both a +substantial memory overhead as well as a performance overhead. + +Here's a sketch of a library that operates on color images plus a +simple benchmark. First, the plain Lua version: + + local floor = math.floor + + local function image_ramp_green(n) + local img = {} + local f = 255/(n-1) + for i=1,n do + img[i] = { red = 0, green = floor((i-1)*f), blue = 0, alpha = 255 } + end + return img + end + + local function image_to_grey(img, n) + for i=1,n do + local y = floor(0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue) + img[i].red = y; img[i].green = y; img[i].blue = y + end + end + + local N = 400*400 + local img = image_ramp_green(N) + for i=1,1000 do + image_to_grey(img, N) + end + +This creates a table with 160.000 pixels, each of which is a table +holding four number values in the range of 0-255. First an image with a +green ramp is created (1D for simplicity), then the image is converted +to greyscale 1000 times. Yes, that's silly, but I was in need of a +simple example ... + +And here's the FFI version. The modified parts have been marked in +bold: + + ① + + + + + + ② + + ③ + ④ + + + + + + + ③ + ⑤local ffi = require("ffi") + ffi.cdef[[ + typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel; + ]] + + local function image_ramp_green(n) + local img = ffi.new("rgba_pixel[?]", n) + local f = 255/(n-1) + for i=0,n-1 do + img[i].green = i*f + img[i].alpha = 255 + end + return img + end + + local function image_to_grey(img, n) + for i=0,n-1 do + local y = 0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue + img[i].red = y; img[i].green = y; img[i].blue = y + end + end + + local N = 400*400 + local img = image_ramp_green(N) + for i=1,1000 do + image_to_grey(img, N) + end + +Ok, so that wasn't too difficult: + +First, load the FFI library and declare the low-level data type. Here +we choose a C which holds four byte fields, one for each +component of a 4x8 bit RGBA pixel. + +Creating the data structure with C is straightforward +E the C<'?'> is a placeholder for the number of elements of a +variable-length array. + +C arrays are zero-based, so the indexes have to run from C<0> to +C. One might want to allocate one more element instead to simplify +converting legacy code. + +Since C zero-fills the array by default, we only need to set +the green and the alpha fields. + +The calls to C can be omitted here, because +floating-point numbers are already truncated towards zero when +converting them to an integer. This happens implicitly when the number +is stored in the fields of each pixel. + +Now let's have a look at the impact of the changes: first, memory +consumption for the image is down from 22 Megabytes to 640 Kilobytes +(400*400*4 bytes). That's a factor of 35x less! So, yes, tables do have +a noticeable overhead. BTW: The original program would consume 40 +Megabytes in plain Lua (on x64). + +Next, performance: the pure Lua version runs in 9.57 seconds (52.9 +seconds with the Lua interpreter) and the FFI version runs in 0.48 +seconds on my machine (YMMV). That's a factor of 20x faster (110x +faster than the Lua interpreter). + +The avid reader may notice that converting the pure Lua version over to +use array indexes for the colors (C<[1]> instead of C<.red>, C<[2]> +instead of C<.green> etc.) ought to be more compact and faster. This is +certainly true (by a factor of ~1.7x). Switching to a struct-of-arrays +would help, too. + +However the resulting code would be less idiomatic and rather +error-prone. And it still doesn't get even close to the performance of +the FFI version of the code. Also, high-level data structures cannot be +easily passed to other C functions, especially I/O functions, without +undue conversion penalties. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_ffi.html +# 10336 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/ext_ffi_api.pod b/doc/LuaJIT-2.1/ext_ffi_api.pod new file mode 100644 index 0000000..174ad5b --- /dev/null +++ b/doc/LuaJIT-2.1/ext_ffi_api.pod @@ -0,0 +1,503 @@ +=pod + +LuaJIT + +=head1 C API Functions + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +This page describes the API functions provided by the FFI library in +detail. It's recommended to read through the introduction and the FFI +tutorial first. + +=head2 Glossary + +=over + +=item * B E An abstract C type declaration (a Lua +string). + +=item * B E A C type object. This is a special kind of +B returned by C. It serves as a B +constructor when called. + +=item * B E A C data object. It holds a value of the +corresponding B. + +=item * B E A C type specification which can be used for +most of the API functions. Either a B, a B or a B +serving as a template type. + +=item * B E A callback object. This is a C data object +holding a special function pointer. Calling this function from C code +runs an associated Lua function. + +=item * B E A variable-length array is declared with a C +instead of the number of elements, e.g. C<"int[?]">. The number of +elements (C) must be given when it's created. + +=item * B E A variable-length struct is a C C type +where the last element is a B. The same rules for declaration and +creation apply. + +=back + +=head2 Declaring and Accessing External Symbols + +External symbols must be declared first and can then be accessed by +indexing a C library namespace, which automatically binds the symbol to +a specific library. + +=head2 C + +Adds multiple C declarations for types or external symbols (named +variables or functions). C must be a Lua string. It's recommended +to use the syntactic sugar for string arguments as follows: + + ffi.cdef[[ + typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef. + int dofoo(foo_t *f, int n); /* Declare an external C function. */ + ]] + +The contents of the string (the part in green above) must be a sequence +of C declarations, separated by semicolons. The trailing semicolon for +a single declaration may be omitted. + +Please note that external symbols are only I, but they are +I to any specific address, yet. Binding is achieved with C +library namespaces (see below). + +C declarations are not passed through a C pre-processor, yet. No +pre-processor tokens are allowed, except for C<#pragma pack>. Replace +C<#define> in existing C header files with C, C or +C and/or pass the files through an external C pre-processor +(once). Be careful not to include unneeded or redundant declarations +from unrelated header files. + +=head2 C + +This is the default C library namespace E note the uppercase +C<'C'>. It binds to the default set of symbols or libraries on the +target system. These are more or less the same as a C compiler would +offer by default, without specifying extra link libraries. + +On POSIX systems, this binds to symbols in the default or global +namespace. This includes all exported symbols from the executable and +any libraries loaded into the global namespace. This includes at least +C, C, C (on Linux), C (if compiled with +GCC), as well as any exported symbols from the Lua/C API provided by +LuaJIT itself. + +On Windows systems, this binds to symbols exported from the C<*.exe>, +the C (i.e. the Lua/C API provided by LuaJIT itself), the C +runtime library LuaJIT was linked with (C), +C, C and C. + +=head2 C + +This loads the dynamic library given by C and returns a new C +library namespace which binds to its symbols. On POSIX systems, if +C is C, the library symbols are loaded into the global +namespace, too. + +If C is a path, the library is loaded from this path. Otherwise +C is canonicalized in a system-dependent way and searched in the +default search path for dynamic libraries: + +On POSIX systems, if the name contains no dot, the extension C<.so> is +appended. Also, the C prefix is prepended if necessary. So +C looks for C<"libz.so"> in the default shared library +search path. + +On Windows systems, if the name contains no dot, the extension C<.dll> +is appended. So C looks for C<"ws2_32.dll"> in the +default DLL search path. + +=head2 Creating cdata Objects + +The following API functions create cdata objects (C returns +C<"cdata">). All created cdata objects are garbage collected. + +=head2 cdata = ffi.new(ct [,nelem] [,init...]) + +cdata = I([nelem,] [init...]) + +Creates a cdata object for the given C. VLA/VLS types require the +C argument. The second syntax uses a ctype as a constructor and +is otherwise fully equivalent. + +The cdata object is initialized according to the rules for +initializers, using the optional C arguments. Excess initializers +cause an error. + +Performance notice: if you want to create many objects of one kind, +parse the cdecl only once and get its ctype with C. Then +use the ctype as a constructor repeatedly. + +Please note that an anonymous C declaration implicitly creates +a new and distinguished ctype every time you use it for C. +This is probably B what you want, especially if you create more +than one cdata object. Different anonymous C are not +considered assignment-compatible by the C standard, even though they +may have the same fields! Also, they are considered different types by +the JIT-compiler, which may cause an excessive number of traces. It's +strongly suggested to either declare a named C or C +with C or to create a single ctype object for an anonymous +C with C. + +=head2 C + +Creates a ctype object for the given C. + +This function is especially useful to parse a cdecl only once and then +use the resulting ctype object as a constructor. + +=head2 C + +Creates a scalar cdata object for the given C. The cdata object is +initialized with C using the "cast" variant of the C type +conversion rules. + +This functions is mainly useful to override the pointer compatibility +checks or to convert pointers to addresses or vice versa. + +=head2 C + +Creates a ctype object for the given C and associates it with a +metatable. Only C/C types, complex numbers and vectors +are allowed. Other types may be wrapped in a C, if needed. + +The association with a metatable is permanent and cannot be changed +afterwards. Neither the contents of the C nor the contents +of an C<__index> table (if any) may be modified afterwards. The +associated metatable automatically applies to all uses of this type, no +matter how the objects are created or where they originate from. Note +that pre-defined operations on types have precedence (e.g. declared +field names cannot be overriden). + +All standard Lua metamethods are implemented. These are called +directly, without shortcuts and on any mix of types. For binary +operations, the left operand is checked first for a valid ctype +metamethod. The C<__gc> metamethod only applies to C/C +types and performs an implicit C call during creation of an +instance. + +=head2 C + +Associates a finalizer with a pointer or aggregate cdata object. The +cdata object is returned unchanged. + +This function allows safe integration of unmanaged resources into the +automatic memory management of the LuaJIT garbage collector. Typical +usage: + + local p = ffi.gc(ffi.C.malloc(n), ffi.C.free) + ... + p = nil -- Last reference to p is gone. + -- GC will eventually run finalizer: ffi.C.free(p) + +A cdata finalizer works like the C<__gc> metamethod for userdata +objects: when the last reference to a cdata object is gone, the +associated finalizer is called with the cdata object as an argument. +The finalizer can be a Lua function or a cdata function or cdata +function pointer. An existing finalizer can be removed by setting a +C finalizer, e.g. right before explicitly deleting a resource: + + ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory. + +=head2 C Type Information + +The following API functions return information about C types. They are +most useful for inspecting cdata objects. + +=head2 C + +Returns the size of C in bytes. Returns C if the size is not +known (e.g. for C<"void"> or function types). Requires C for +VLA/VLS types, except for cdata objects. + +=head2 C + +Returns the minimum required alignment for C in bytes. + +=head2 C + +Returns the offset (in bytes) of C relative to the start of +C, which must be a C. Additionally returns the position and +the field size (in bits) for bit fields. + +=head2 C + +Returns C if C has the C type given by C. Returns +C otherwise. + +C type qualifiers (C etc.) are ignored. Pointers are checked +with the standard pointer compatibility rules, but without any special +treatment for C. If C specifies a C/C, then +a pointer to this type is accepted, too. Otherwise the types must match +exactly. + +Note: this function accepts all kinds of Lua objects for the C +argument, but always returns C for non-cdata objects. + +=head2 Utility Functions + +=head2 C + +Returns the error number set by the last C function call which +indicated an error condition. If the optional C argument is +present, the error number is set to the new value and the previous +value is returned. + +This function offers a portable and OS-independent way to get and set +the error number. Note that only I C functions set the error +number. And it's only significant if the function actually indicated an +error condition (e.g. with a return value of C<-1> or C). +Otherwise, it may or may not contain any previously set value. + +You're advised to call this function only when needed and as close as +possible after the return of the related C function. The C value +is preserved across hooks, memory allocations, invocations of the JIT +compiler and other internal VM activity. The same applies to the value +returned by C on Windows, but you need to declare and +call it yourself. + +=head2 C + +Creates an interned Lua string from the data pointed to by C. + +If the optional argument C is missing, C is converted to a +C<"char *"> and the data is assumed to be zero-terminated. The length +of the string is computed with C. + +Otherwise C is converted to a C<"void *"> and C gives the +length of the data. The data may contain embedded zeros and need not be +byte-oriented (though this may cause endianess issues). + +This function is mainly useful to convert (temporary) C<"const char *"> +pointers returned by C functions to Lua strings and store them or pass +them to other functions expecting a Lua string. The Lua string is an +(interned) copy of the data and bears no relation to the original data +area anymore. Lua strings are 8 bit clean and may be used to hold +arbitrary, non-character data. + +Performance notice: it's faster to pass the length of the string, if +it's known. E.g. when the length is returned by a C call like +C. + +=head2 ffi.copy(dst, src, len) + +ffi.copy(dst, str) + +Copies the data pointed to by C to C. C is converted to +a C<"void *"> and C is converted to a C<"const void *">. + +In the first syntax, C gives the number of bytes to copy. Caveat: +if C is a Lua string, then C must not exceed C<#src+1>. + +In the second syntax, the source of the copy must be a Lua string. All +bytes of the string I are copied to C +(i.e. C<#src+1> bytes). + +Performance notice: C may be used as a faster (inlinable) +replacement for the C library functions C, C and +C. + +=head2 C + +Fills the data pointed to by C with C constant bytes, given +by C. If C is omitted, the data is zero-filled. + +Performance notice: C may be used as a faster (inlinable) +replacement for the C library function C. Please +note the different order of arguments! + +=head2 Target-specific Information + +=head2 C + +Returns C if C (a Lua string) applies for the target ABI +(Application Binary Interface). Returns C otherwise. The +following parameters are currently defined: + +Parameter + +Description + +32bit + +32 bit architecture + +64bit + +64 bit architecture + +le + +Little-endian architecture + +be + +Big-endian architecture + +fpu + +Target has a hardware FPU + +softfp + +softfp calling conventions + +hardfp + +hardfp calling conventions + +eabi + +EABI variant of the standard ABI + +win + +Windows variant of the standard ABI + +gc64 + +64 bit GC references + +=head2 C + +Contains the target OS name. Same contents as C. + +=head2 C + +Contains the target architecture name. Same contents as C. + +=head2 Methods for Callbacks + +The C types for callbacks have some extra methods: + +=head2 C + +Free the resources associated with a callback. The associated Lua +function is unanchored and may be garbage collected. The callback +function pointer is no longer valid and must not be called anymore (it +may be reused by a subsequently created callback). + +=head2 C + +Associate a new Lua function with a callback. The C type of the +callback and the callback function pointer are unchanged. + +This method is useful to dynamically switch the receiver of callbacks +without creating a new callback each time and registering it again +(e.g. with a GUI library). + +=head2 Extended Standard Library Functions + +The following standard library functions have been extended to work +with cdata objects: + +=head2 C + +Converts a number cdata object to a C and returns it as a Lua +number. This is particularly useful for boxed 64 bit integer values. +Caveat: this conversion may incur a precision loss. + +=head2 C + +Returns a string representation of the value of 64 bit integers +(CnnnB> or CnnnB>) or complex numbers +(CreEimB>). Otherwise returns a string representation +of the C type of a ctype object (C>typeB">>) or a +cdata object (C>typeB: >address">), unless you +override it with a C<__tostring> metamethod (see C). + +=head2 iter, obj, start = pairs(cdata) + +iter, obj, start = ipairs(cdata) + +Calls the C<__pairs> or C<__ipairs> metamethod of the corresponding +ctype. + +=head2 Extensions to the Lua Parser + +The parser for Lua source code treats numeric literals with the +suffixes C or C as signed or unsigned 64 bit integers. Case +doesn't matter, but uppercase is recommended for readability. It +handles decimal (C<42LL>), hexadecimal (C<0x2aLL>) and binary +(C<0b101010LL>) literals. + +The imaginary part of complex numbers can be specified by suffixing +number literals with C or C, e.g. C<12.5i>. Caveat: you'll need +to use C<1i> to get an imaginary part with the value one, since C +itself still refers to a variable named C. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_ffi_api.html +# 21471 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render +# Deleting phrasal "code" element (`tt_157) because it has super-phrasal elements (`br_3, `br_4) as children. +# Deleting phrasal "code" element (`tt_113) because it has super-phrasal elements (`br_2) as children. +# Deleting phrasal "code" element (`tt_41) because it has super-phrasal elements (`br_1) as children. diff --git a/doc/LuaJIT-2.1/ext_ffi_semantics.pod b/doc/LuaJIT-2.1/ext_ffi_semantics.pod new file mode 100644 index 0000000..309a1f5 --- /dev/null +++ b/doc/LuaJIT-2.1/ext_ffi_semantics.pod @@ -0,0 +1,1387 @@ +=pod + +LuaJIT + +=head1 FFI Semantics + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +This page describes the detailed semantics underlying the FFI library +and its interaction with both Lua and C code. + +Given that the FFI library is designed to interface with C code and +that declarations can be written in plain C syntax, B, wherever possible. Some minor +concessions are needed for smoother interoperation with Lua language +semantics. + +Please don't be overwhelmed by the contents of this page E this +is a reference and you may need to consult it, if in doubt. It doesn't +hurt to skim this page, but most of the semantics "just work" as you'd +expect them to work. It should be straightforward to write applications +using the LuaJIT FFI for developers with a C or C++ background. + +=head2 C Language Support + +The FFI library has a built-in C parser with a minimal memory +footprint. It's used by the ffi.* library functions to declare C types +or external symbols. + +It's only purpose is to parse C declarations, as found e.g. in C header +files. Although it does evaluate constant expressions, it's I a C +compiler. The body of C C function definitions is simply +ignored. + +Also, this is I a validating C parser. It expects and accepts +correctly formed C declarations, but it may choose to ignore bad +declarations or show rather generic error messages. If in doubt, please +check the input against your favorite C compiler. + +The C parser complies to the B plus the +following extensions: + +=over + +=item * The C<'\e'> escape in character and string literals. + +=item * The C99/C++ boolean type, declared with the keywords C or +C<_Bool>. + +=item * Complex numbers, declared with the keywords C or +C<_Complex>. + +=item * Two complex number types: C (aka C) +and C. + +=item * Vector types, declared with the GCC C or C +attribute. + +=item * Unnamed ('transparent') C/C fields inside a +C/C. + +=item * Incomplete C declarations, handled like incomplete +C declarations. + +=item * Unnamed C fields inside a C/C. This is +similar to a scoped C++ C, except that declared constants are +visible in the global namespace, too. + +=item * Scoped C declarations inside a C/C +(from C++). + +=item * Zero-length arrays (C<[0]>), empty C/C, +variable-length arrays (VLA, C<[?]>) and variable-length structs (VLS, +with a trailing VLA). + +=item * C++ reference types (C). + +=item * Alternate GCC keywords with 'C<__>', e.g. C<__const__>. + +=item * GCC C<__attribute__> with the following attributes: C, +C, C, C, C, C, C, +C. + +=item * The GCC C<__extension__> keyword and the GCC C<__alignof__> +operator. + +=item * GCC C<__asm__("symname")> symbol name redirection for function +declarations. + +=item * MSVC keywords for fixed-length types: C<__int8>, C<__int16>, +C<__int32> and C<__int64>. + +=item * MSVC C<__cdecl>, C<__fastcall>, C<__stdcall>, C<__thiscall>, +C<__ptr32>, C<__ptr64>, C<__declspec(align(n))> and C<#pragma pack>. + +=item * All other GCC/MSVC-specific attributes are ignored. + +=back + +The following C types are pre-defined by the C parser (like a +C, except re-declarations will be ignored): + +=over + +=item * Vararg handling: C, C<__builtin_va_list>, +C<__gnuc_va_list>. + +=item * From Cstddef.hE>: C, C, +C. + +=item * From Cstdint.hE>: C, C, C, +C, C, C, C, C, +C, C. + +=item * From Cunistd.hE> (POSIX): C. + +=back + +You're encouraged to use these types in preference to compiler-specific +extensions or target-dependent standard types. E.g. C differs in +signedness and C differs in size, depending on the target +architecture and platform ABI. + +The following C features are B supported: + +=over + +=item * A declaration must always have a type specifier; it doesn't +default to an C type. + +=item * Old-style empty function declarations (K&R) are not allowed. +All C functions must have a proper prototype declaration. A function +declared without parameters (C) is treated as a function +taking zero arguments, like in C++. + +=item * The C C type is parsed correctly, but there's no +support for the related conversions, accesses or arithmetic operations. + +=item * Wide character strings and character literals are not +supported. + +=item * See below for features that are currently not implemented. + +=back + +=head2 C Type Conversion Rules + +=head2 Conversions from C types to Lua objects + +These conversion rules apply for I to C types: indexing +pointers, arrays or C/C types; reading external +variables or constant values; retrieving return values from C calls: + +Input + +Conversion + +Output + +C, C + +Esign-ext C E C + +number + +C, C + +Ezero-ext C E C + +number + +C, C + +E C + +number + +C, C + +boxed value + +64 bit int cdata + +C, C + +E C + +number + +C + +0 E C, otherwise C + +boolean + +C + +boxed value + +enum cdata + +Complex number + +boxed value + +complex cdata + +Vector + +boxed value + +vector cdata + +Pointer + +boxed value + +pointer cdata + +Array + +boxed reference + +reference cdata + +C/C + +boxed reference + +reference cdata + +Bitfields are treated like their underlying type. + +Reference types are dereferenced I a conversion can take place +E the conversion is applied to the C type pointed to by the +reference. + +=head2 Conversions from Lua objects to C types + +These conversion rules apply for I to C types: indexing +pointers, arrays or C/C types; initializing cdata +objects; casts to C types; writing to external variables; passing +arguments to C calls: + +Input + +Conversion + +Output + +number + +E + +C + +boolean + +C E 0, C E 1 + +C + +nil + +C E + +C<(void *)> + +lightuserdata + +lightuserdata address E + +C<(void *)> + +userdata + +userdata payload E + +C<(void *)> + +io.* file + +get FILE * handle E + +C<(void *)> + +string + +match against C constant + +C + +string + +copy string data + zero-byte + +C, C + +string + +string data E + +C + +function + +create callback E + +C function type + +table + +table initializer + +Array + +table + +table initializer + +C/C + +cdata + +cdata payload E + +C type + +If the result type of this conversion doesn't match the C type of the +destination, the conversion rules between C types are applied. + +Reference types are immutable after initialization ("no re-seating of +references"). For initialization purposes or when passing values to +reference parameters, they are treated like pointers. Note that unlike +in C++, there's no way to implement automatic reference generation of +variables under the Lua language semantics. If you want to call a +function with a reference parameter, you need to explicitly pass a +one-element array. + +=head2 Conversions between C types + +These conversion rules are more or less the same as the standard C +conversion rules. Some rules only apply to casts, or require pointer or +type compatibility: + +Input + +Conversion + +Output + +Signed integer + +Enarrow or sign-extend + +Integer + +Unsigned integer + +Enarrow or zero-extend + +Integer + +Integer + +Eround + +C, C + +C, C + +Etrunc C Enarrow + +C<(u)int8_t>, C<(u)int16_t> + +C, C + +Etrunc + +C<(u)int32_t>, C<(u)int64_t> + +C, C + +Eround + +C, C + +Number + +n == 0 E 0, otherwise 1 + +C + +C + +C E 0, C E 1 + +Number + +Complex number + +convert real part + +Number + +Number + +convert real part, imag = 0 + +Complex number + +Complex number + +convert real and imag part + +Complex number + +Number + +convert scalar and replicate + +Vector + +Vector + +copy (same size) + +Vector + +C/C + +take base address (compat) + +Pointer + +Array + +take base address (compat) + +Pointer + +Function + +take function address + +Function pointer + +Number + +convert via C (cast) + +Pointer + +Pointer + +convert address (compat/cast) + +Pointer + +Pointer + +convert address (cast) + +Integer + +Array + +convert base address (cast) + +Integer + +Array + +copy (compat) + +Array + +C/C + +copy (identical type) + +C/C + +Bitfields or C types are treated like their underlying type. + +Conversions not listed above will raise an error. E.g. it's not +possible to convert a pointer to a complex number or vice versa. + +=head2 Conversions for vararg C function arguments + +The following default conversion rules apply when passing Lua objects +to the variable argument part of vararg C functions: + +Input + +Conversion + +Output + +number + +E + +C + +boolean + +C E 0, C E 1 + +C + +nil + +C E + +C<(void *)> + +userdata + +userdata payload E + +C<(void *)> + +lightuserdata + +lightuserdata address E + +C<(void *)> + +string + +string data E + +C + +C cdata + +E + +C + +Array cdata + +take base address + +Element pointer + +C/C cdata + +take base address + +C/C pointer + +Function cdata + +take function address + +Function pointer + +Any other cdata + +no conversion + +C type + +To pass a Lua object, other than a cdata object, as a specific type, +you need to override the conversion rules: create a temporary cdata +object with a constructor or a cast and initialize it with the value to +pass: + +Assuming C is a Lua number, here's how to pass it as an integer to a +vararg function: + + ffi.cdef[[ + int printf(const char *fmt, ...); + ]] + ffi.C.printf("integer value: %d\n", ffi.new("int", x)) + +If you don't do this, the default Lua number E C +conversion rule applies. A vararg C function expecting an integer will +see a garbled or uninitialized value. + +=head2 Initializers + +Creating a cdata object with C or the equivalent constructor +syntax always initializes its contents, too. Different rules apply, +depending on the number of optional initializers and the C types +involved: + +=over + +=item * If no initializers are given, the object is filled with zero +bytes. + +=item * Scalar types (numbers and pointers) accept a single +initializer. The Lua object is converted to the scalar C type. + +=item * Valarrays (complex numbers and vectors) are treated like +scalars when a single initializer is given. Otherwise they are treated +like regular arrays. + +=item * Aggregate types (arrays and structs) accept either a single +cdata initializer of the same type (copy constructor), a single table +initializer, or a flat list of initializers. + +=item * The elements of an array are initialized, starting at index +zero. If a single initializer is given for an array, it's repeated for +all remaining elements. This doesn't happen if two or more initializers +are given: all remaining uninitialized elements are filled with zero +bytes. + +=item * Byte arrays may also be initialized with a Lua string. This +copies the whole string plus a terminating zero-byte. The copy stops +early only if the array has a known, fixed size. + +=item * The fields of a C are initialized in the order of their +declaration. Uninitialized fields are filled with zero bytes. + +=item * Only the first field of a C can be initialized with a +flat initializer. + +=item * Elements or fields which are aggregates themselves are +initialized with a I initializer, but this may be a table +initializer or a compatible aggregate. + +=item * Excess initializers cause an error. + +=back + +=head2 Table Initializers + +The following rules apply if a Lua table is used to initialize an Array +or a C/C: + +=over + +=item * If the table index C<[0]> is non-C, then the table is +assumed to be zero-based. Otherwise it's assumed to be one-based. + +=item * Array elements, starting at index zero, are initialized +one-by-one with the consecutive table elements, starting at either +index C<[0]> or C<[1]>. This process stops at the first C table +element. + +=item * If exactly one array element was initialized, it's repeated for +all the remaining elements. Otherwise all remaining uninitialized +elements are filled with zero bytes. + +=item * The above logic only applies to arrays with a known fixed size. +A VLA is only initialized with the element(s) given in the table. +Depending on the use case, you may need to explicitly add a C or +C<0> terminator to a VLA. + +=item * A C/C can be initialized in the order of the +declaration of its fields. Each field is initialized with consecutive +table elements, starting at either index C<[0]> or C<[1]>. This process +stops at the first C table element. + +=item * Otherwise, if neither index C<[0]> nor C<[1]> is present, a +C/C is initialized by looking up each field name (as a +string key) in the table. Each non-C value is used to initialize +the corresponding field. + +=item * Uninitialized fields of a C are filled with zero bytes, +except for the trailing VLA of a VLS. + +=item * Initialization of a C stops after one field has been +initialized. If no field has been initialized, the C is filled +with zero bytes. + +=item * Elements or fields which are aggregates themselves are +initialized with a I initializer, but this may be a nested +table initializer (or a compatible aggregate). + +=item * Excess initializers for an array cause an error. Excess +initializers for a C/C are ignored. Unrelated table +entries are ignored, too. + +=back + +Example: + + local ffi = require("ffi") + + ffi.cdef[[ + struct foo { int a, b; }; + union bar { int i; double d; }; + struct nested { int x; struct foo y; }; + ]] + + ffi.new("int[3]", {}) --> 0, 0, 0 + ffi.new("int[3]", {1}) --> 1, 1, 1 + ffi.new("int[3]", {1,2}) --> 1, 2, 0 + ffi.new("int[3]", {1,2,3}) --> 1, 2, 3 + ffi.new("int[3]", {[0]=1}) --> 1, 1, 1 + ffi.new("int[3]", {[0]=1,2}) --> 1, 2, 0 + ffi.new("int[3]", {[0]=1,2,3}) --> 1, 2, 3 + ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers + + ffi.new("struct foo", {}) --> a = 0, b = 0 + ffi.new("struct foo", {1}) --> a = 1, b = 0 + ffi.new("struct foo", {1,2}) --> a = 1, b = 2 + ffi.new("struct foo", {[0]=1,2}) --> a = 1, b = 2 + ffi.new("struct foo", {b=2}) --> a = 0, b = 2 + ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2 'c' is ignored + + ffi.new("union bar", {}) --> i = 0, d = 0.0 + ffi.new("union bar", {1}) --> i = 1, d = ? + ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ? '2' is ignored + ffi.new("union bar", {d=2}) --> i = ?, d = 2.0 + + ffi.new("struct nested", {1,{2,3}}) --> x = 1, y.a = 2, y.b = 3 + ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3 + +=head2 Operations on cdata Objects + +All of the standard Lua operators can be applied to cdata objects or a +mix of a cdata object and another Lua object. The following list shows +the pre-defined operations. + +Reference types are dereferenced I performing each of the +operations below E the operation is applied to the C type +pointed to by the reference. + +The pre-defined operations are always tried first before deferring to a +metamethod or index table (if any) for the corresponding ctype (except +for C<__new>). An error is raised if the metamethod lookup or index +table lookup fails. + +=head2 Indexing a cdata object + +=over + +=item * B: a cdata pointer/array can be +indexed by a cdata number or a Lua number. The element address is +computed as the base address plus the number value multiplied by the +element size in bytes. A read access loads the element value and +converts it to a Lua object. A write access converts a Lua object to +the element type and stores the converted value to the element. An +error is raised if the element size is undefined or a write access to a +constant element is attempted. + +=item * B/C field>: a cdata +C/C or a pointer to a C/C can be +dereferenced by a string key, giving the field name. The field address +is computed as the base address plus the relative offset of the field. +A read access loads the field value and converts it to a Lua object. A +write access converts a Lua object to the field type and stores the +converted value to the field. An error is raised if a write access to a +constant C/C or a constant field is attempted. Scoped +enum constants or static constants are treated like a constant field. + +=item * B: a complex number can be indexed +either by a cdata number or a Lua number with the values 0 or 1, or by +the strings C<"re"> or C<"im">. A read access loads the real part +(C<[0]>, C<.re>) or the imaginary part (C<[1]>, C<.im>) part of a +complex number and converts it to a Lua number. The sub-parts of a +complex number are immutable E assigning to an index of a +complex number raises an error. Accessing out-of-bound indexes returns +unspecified results, but is guaranteed not to trigger memory access +violations. + +=item * B: a vector is treated like an array for +indexing purposes, except the vector elements are immutable E +assigning to an index of a vector raises an error. + +=back + +A ctype object can be indexed with a string key, too. The only +pre-defined operation is reading scoped constants of C/C +types. All other accesses defer to the corresponding metamethods or +index tables (if any). + +Note: since there's (deliberately) no address-of operator, a cdata +object holding a value type is effectively immutable after +initialization. The JIT compiler benefits from this fact when applying +certain optimizations. + +As a consequence, the I of complex numbers and vectors are +immutable. But the elements of an aggregate holding these types I +be modified of course. I.e. you cannot assign to C, but you +can assign a (newly created) complex number to C. + +The JIT compiler implements strict aliasing rules: accesses to +different types do B alias, except for differences in signedness +(this applies even to C pointers, unlike C99). Type punning +through unions is explicitly detected and allowed. + +=head2 Calling a cdata object + +=over + +=item * B: a ctype object can be called and used as a +constructor. This is equivalent to C, unless a +C<__new> metamethod is defined. The C<__new> metamethod is called with +the ctype object plus any other arguments passed to the contructor. +Note that you have to use C inside of it, since calling +C would cause infinite recursion. + +=item * B: a cdata function or cdata function pointer +can be called. The passed arguments are converted to the C types of the +parameters given by the function declaration. Arguments passed to the +variable argument part of vararg C function use special conversion +rules. This C function is called and the return value (if any) is +converted to a Lua object. + +On Windows/x86 systems, C<__stdcall> functions are automatically +detected and a function declared as C<__cdecl> (the default) is +silently fixed up after the first call. + +=back + +=head2 Arithmetic on cdata objects + +=over + +=item * B: a cdata pointer/array and a cdata number +or a Lua number can be added or subtracted. The number must be on the +right hand side for a subtraction. The result is a pointer of the same +type with an address plus or minus the number value multiplied by the +element size in bytes. An error is raised if the element size is +undefined. + +=item * B: two compatible cdata pointers/arrays can +be subtracted. The result is the difference between their addresses, +divided by the element size in bytes. An error is raised if the element +size is undefined or zero. + +=item * B<64 bit integer arithmetic>: the standard arithmetic operators +(C<+ - * / % ^> and unary minus) can be applied to two cdata numbers, +or a cdata number and a Lua number. If one of them is an C, +the other side is converted to an C and an unsigned +arithmetic operation is performed. Otherwise both sides are converted +to an C and a signed arithmetic operation is performed. The +result is a boxed 64 bit cdata object. + +If one of the operands is an C and the other operand is a string, +the string is converted to the value of a matching C constant +before the above conversion. + +These rules ensure that 64 bit integers are "sticky". Any expression +involving at least one 64 bit integer operand results in another one. +The undefined cases for the division, modulo and power operators return +C<2LL ^ 63> or C<2ULL ^ 63>. + +You'll have to explicitly convert a 64 bit integer to a Lua number +(e.g. for regular floating-point calculations) with C. But +note this may incur a precision loss. + +=item * B<64 bit bitwise operations>: the rules for 64 bit arithmetic +operators apply analogously. + +Unlike the other C operations, C converts a cdata +number via C to C and returns a Lua number. + +For C, C and C, the conversion to +C or C applies to I arguments, if I +argument is a cdata number. + +For all other operations, only the first argument is used to determine +the output type. This implies that a cdata number as a shift count for +shifts and rotates is accepted, but that alone does I cause a +cdata number output. + +=back + +=head2 Comparisons of cdata objects + +=over + +=item * B: two compatible cdata pointers/arrays can +be compared. The result is the same as an unsigned comparison of their +addresses. C is treated like a C pointer, which is +compatible with any other pointer type. + +=item * B<64 bit integer comparison>: two cdata numbers, or a cdata +number and a Lua number can be compared with each other. If one of them +is an C, the other side is converted to an C and an +unsigned comparison is performed. Otherwise both sides are converted to +an C and a signed comparison is performed. + +If one of the operands is an C and the other operand is a string, +the string is converted to the value of a matching C constant +before the above conversion. + +=item * B never raise an error. +Even incompatible pointers can be compared for equality by address. Any +other incompatible comparison (also with non-cdata objects) treats the +two sides as unequal. + +=back + +=head2 cdata objects as table keys + +Lua tables may be indexed by cdata objects, but this doesn't provide +any useful semantics E B + +A cdata object is treated like any other garbage-collected object and +is hashed and compared by its address for table indexing. Since there's +no interning for cdata value types, the same value may be boxed in +different cdata objects with different addresses. Thus C +and C usually B point to the same hash slot and they +certainly B point to the same hash slot as C. + +It would seriously drive up implementation complexity and slow down the +common case, if one were to add extra handling for by-value hashing and +comparisons to Lua tables. Given the ubiquity of their use inside the +VM, this is not acceptable. + +There are three viable alternatives, if you really need to use cdata +objects as keys: + +=over + +=item * If you can get by with the precision of Lua numbers (52 bits), +then use C on a cdata number or combine multiple fields of +a cdata aggregate to a Lua number. Then use the resulting Lua number as +a key when indexing tables. + +One obvious benefit: C B point to the same slot +as C. + +=item * Otherwise use either C on 64 bit integers or +complex numbers or combine multiple fields of a cdata aggregate to a +Lua string (e.g. with C). Then use the resulting Lua +string as a key when indexing tables. + +=item * Create your own specialized hash table implementation using the +C types provided by the FFI library, just like you would in C code. +Ultimately this may give much better performance than the other +alternatives or what a generic by-value hash table could possibly +provide. + +=back + +=head2 Parameterized Types + +To facilitate some abstractions, the two functions C and +C support parameterized types in C declarations. Note: none +of the other API functions taking a cdecl allow this. + +Any place you can write a B name>, an B or a +B in a declaration, you can write C<$> (the dollar sign) +instead. These placeholders are replaced in order of appearance with +the arguments following the cdecl string: + + -- Declare a struct with a parameterized field type and name: + ffi.cdef([[ + typedef struct { $ $; } foo_t; + ]], type1, name1) + + -- Anonymous struct with dynamic names: + local bar_t = ffi.typeof("struct { int $, $; }", name1, name2) + -- Derived pointer type: + local bar_ptr_t = ffi.typeof("$ *", bar_t) + + -- Parameterized dimensions work even where a VLA won't work: + local matrix_t = ffi.typeof("uint8_t[$][$]", width, height) + +Caveat: this is I simple text substitution! A passed ctype or +cdata object is treated like the underlying type, a passed string is +considered an identifier and a number is considered a number. You must +not mix this up: e.g. passing C<"int"> as a string doesn't work in +place of a type, you'd need to use C instead. + +The main use for parameterized types are libraries implementing +abstract data types (E example), similar to what can be +achieved with C++ template metaprogramming. Another use case are +derived types of anonymous structs, which avoids pollution of the +global struct namespace. + +Please note that parameterized types are a nice tool and indispensable +for certain use cases. But you'll want to use them sparingly in regular +code, e.g. when all types are actually fixed. + +=head2 Garbage Collection of cdata Objects + +All explicitly (C, C etc.) or implicitly +(accessors) created cdata objects are garbage collected. You need to +ensure to retain valid references to cdata objects somewhere on a Lua +stack, an upvalue or in a Lua table while they are still in use. Once +the last reference to a cdata object is gone, the garbage collector +will automatically free the memory used by it (at the end of the next +GC cycle). + +Please note that pointers themselves are cdata objects, however they +are B followed by the garbage collector. So e.g. if you assign a +cdata array to a pointer, you must keep the cdata object holding the +array alive as long as the pointer is still in use: + + ffi.cdef[[ + typedef struct { int *a; } foo_t; + ]] + + local s = ffi.new("foo_t", ffi.new("int[10]")) -- WRONG! + + local a = ffi.new("int[10]") -- OK + local s = ffi.new("foo_t", a) + -- Now do something with 's', but keep 'a' alive until you're done. + +Similar rules apply for Lua strings which are implicitly converted to +C<"const char *">: the string object itself must be referenced +somewhere or it'll be garbage collected eventually. The pointer will +then point to stale data, which may have already been overwritten. Note +that I are automatically kept alive as long as the +function containing it (actually its prototype) is not garbage +collected. + +Objects which are passed as an argument to an external C function are +kept alive until the call returns. So it's generally safe to create +temporary cdata objects in argument lists. This is a common idiom for +passing specific C types to vararg functions. + +Memory areas returned by C functions (e.g. from C) must be +manually managed, of course (or use C). Pointers to cdata +objects are indistinguishable from pointers returned by C functions +(which is one of the reasons why the GC cannot follow them). + +=head2 Callbacks + +The LuaJIT FFI automatically generates special callback functions +whenever a Lua function is converted to a C function pointer. This +associates the generated callback function pointer with the C type of +the function pointer and the Lua function object (closure). + +This can happen implicitly due to the usual conversions, e.g. when +passing a Lua function to a function pointer argument. Or you can use +C to explicitly cast a Lua function to a C function +pointer. + +Currently only certain C function types can be used as callback +functions. Neither C vararg functions nor functions with pass-by-value +aggregate argument or result types are supported. There are no +restrictions for the kind of Lua functions that can be called from the +callback E no checks for the proper number of arguments are +made. The return value of the Lua function will be converted to the +result type and an error will be thrown for invalid conversions. + +It's allowed to throw errors across a callback invocation, but it's not +advisable in general. Do this only if you know the C function, that +called the callback, copes with the forced stack unwinding and doesn't +leak resources. + +One thing that's not allowed, is to let an FFI call into a C function +get JIT-compiled, which in turn calls a callback, calling into Lua +again. Usually this attempt is caught by the interpreter first and the +C function is blacklisted for compilation. + +However, this heuristic may fail under specific circumstances: e.g. a +message polling function might not run Lua callbacks right away and the +call gets JIT-compiled. If it later happens to call back into Lua (e.g. +a rarely invoked error callback), you'll get a VM PANIC with the +message C<"bad callback">. Then you'll need to manually turn off +JIT-compilation with C for the surrounding Lua function that +invokes such a message polling function (or similar). + +=head2 Callback resource handling + +Callbacks take up resources E you can only have a limited number +of them at the same time (500 - 1000, depending on the architecture). +The associated Lua functions are anchored to prevent garbage +collection, too. + +B There is no way +to guess their lifetime, since the C side might store the function +pointer for later use (typical for GUI toolkits). The associated +resources cannot be reclaimed until termination: + + ffi.cdef[[ + typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l); + int EnumWindows(WNDENUMPROC func, intptr_t l); + ]] + + -- Implicit conversion to a callback via function pointer argument. + local count = 0 + ffi.C.EnumWindows(function(hwnd, l) + count = count + 1 + return true + end, 0) + -- The callback is permanent and its resources cannot be reclaimed! + -- Ok, so this may not be a problem, if you do this only once. + +Note: this example shows that you I properly declare C<__stdcall> +callbacks on Windows/x86 systems. The calling convention cannot be +automatically detected, unlike for C<__stdcall> calls I Windows +functions. + +For some use cases it's necessary to free up the resources or to +dynamically redirect callbacks. Use an explicit cast to a C function +pointer and keep the resulting cdata object. Then use the C +or C methods on the cdata object: + + -- Explicitly convert to a callback via cast. + local count = 0 + local cb = ffi.cast("WNDENUMPROC", function(hwnd, l) + count = count + 1 + return true + end) + + -- Pass it to a C function. + ffi.C.EnumWindows(cb, 0) + -- EnumWindows doesn't need the callback after it returns, so free it. + + cb:free() + -- The callback function pointer is no longer valid and its resources + -- will be reclaimed. The created Lua closure will be garbage collected. + +=head2 Callback performance + +B First, the C to Lua transition itself has an +unavoidable cost, similar to a C or C. +Argument and result marshalling add to that cost. And finally, neither +the C compiler nor LuaJIT can inline or optimize across the language +barrier and hoist repeated computations out of a callback function. + +Do not use callbacks for performance-sensitive work: e.g. consider a +numerical integration routine which takes a user-defined function to +integrate over. It's a bad idea to call a user-defined Lua function +from C code millions of times. The callback overhead will be absolutely +detrimental for performance. + +It's considerably faster to write the numerical integration routine +itself in Lua E the JIT compiler will be able to inline the +user-defined function and optimize it together with its calling +context, with very competitive performance. + +As a general guideline: B, because of +existing C APIs. E.g. callback performance is irrelevant for a GUI +application, which waits for user input most of the time, anyway. + +For new designs B: a C function repeatedly +calling a callback for each result. Instead B: +call a C function repeatedly to get a new result. Calls from Lua to C +via the FFI are much faster than the other way round. Most +well-designed libraries already use pull-style APIs (read/write, +get/put). + +=head2 C Library Namespaces + +A C library namespace is a special kind of object which allows access +to the symbols contained in shared libraries or the default symbol +namespace. The default C namespace is automatically created when +the FFI library is loaded. C library namespaces for specific shared +libraries may be created with the C API function. + +Indexing a C library namespace object with a symbol name (a Lua string) +automatically binds it to the library. First the symbol type is +resolved E it must have been declared with C. Then the +symbol address is resolved by searching for the symbol name in the +associated shared libraries or the default symbol namespace. Finally, +the resulting binding between the symbol name, the symbol type and its +address is cached. Missing symbol declarations or nonexistent symbol +names cause an error. + +This is what happens on a B for the different kinds of +symbols: + +=over + +=item * External functions: a cdata object with the type of the +function and its address is returned. + +=item * External variables: the symbol address is dereferenced and the +loaded value is converted to a Lua object and returned. + +=item * Constant values (C or C constants): the +constant is converted to a Lua object and returned. + +=back + +This is what happens on a B: + +=over + +=item * External variables: the value to be written is converted to the +C type of the variable and then stored at the symbol address. + +=item * Writing to constant variables or to any other symbol type +causes an error, like any other attempted write to a constant location. + +=back + +C library namespaces themselves are garbage collected objects. If the +last reference to the namespace object is gone, the garbage collector +will eventually release the shared library reference and remove all +memory associated with the namespace. Since this may trigger the +removal of the shared library from the memory of the running process, +it's generally I to use function cdata objects obtained from +a library if the namespace object may be unreferenced. + +Performance notice: the JIT compiler specializes to the identity of +namespace objects and to the strings used to index it. This effectively +turns function cdata objects into constants. It's not useful and +actually counter-productive to explicitly cache these function objects, +e.g. C. OTOH it I useful to cache the +namespace itself, e.g. C. + +=head2 No Hand-holding! + +The FFI library has been designed as B. The goal +is to interface with C code and C data types with a minimum of +overhead. This means B: access +all memory, overwrite anything in memory, call machine code at any +memory address and so on. + +The FFI library provides B, unlike regular Lua code. +It will happily allow you to dereference a C pointer, to access +arrays out of bounds or to misdeclare C functions. If you make a +mistake, your application might crash, just like equivalent C code +would. + +This behavior is inevitable, since the goal is to provide full +interoperability with C code. Adding extra safety measures, like bounds +checks, would be futile. There's no way to detect misdeclarations of C +functions, since shared libraries only provide symbol names, but no +type information. Likewise there's no way to infer the valid range of +indexes for a returned pointer. + +Again: the FFI library is a low-level library. This implies it needs to +be used with care, but it's flexibility and performance often outweigh +this concern. If you're a C or C++ developer, it'll be easy to apply +your existing knowledge. OTOH writing code for the FFI library is not +for the faint of heart and probably shouldn't be the first exercise for +someone with little experience in Lua, C or C++. + +As a corollary of the above, the FFI library is B. If you're sandboxing untrusted Lua code, you +definitely don't want to give this code access to the FFI library or to +I cdata object (except 64 bit integers or complex numbers). Any +properly engineered Lua sandbox needs to provide safety wrappers for +many of the standard Lua library functions E similar wrappers +need to be written for high-level operations on FFI data types, too. + +=head2 Current Status + +The initial release of the FFI library has some limitations and is +missing some features. Most of these will be fixed in future releases. + +C language support is currently incomplete: + +=over + +=item * C declarations are not passed through a C pre-processor, yet. + +=item * The C parser is able to evaluate most constant expressions +commonly found in C header files. However it doesn't handle the full +range of C expression semantics and may fail for some obscure +constructs. + +=item * C declarations only work for integer types up to +32 bits. Neither declaring string constants nor floating-point +constants is supported. + +=item * Packed C bitfields that cross container boundaries are +not implemented. + +=item * Native vector types may be defined with the GCC C or +C attribute. But no operations other than loading, storing +and initializing them are supported, yet. + +=item * The C type qualifier is currently ignored by compiled +code. + +=item * C silently ignores most re-declarations. Note: avoid +re-declarations which do not conform to C99. The implementation will +eventually be changed to perform strict checks. + +=back + +The JIT compiler already handles a large subset of all FFI operations. +It automatically falls back to the interpreter for unimplemented +operations (you can check for this with the C<-jv> command line +option). The following operations are currently not compiled and may +exhibit suboptimal performance, especially when used in inner loops: + +=over + +=item * Bitfield accesses and initializations. + +=item * Vector operations. + +=item * Table initializers. + +=item * Initialization of nested C/C types. + +=item * Non-default initialization of VLA/VLS or large C types (E +128 bytes or E 16 array elements. + +=item * Conversions from lightuserdata to C. + +=item * Pointer differences for element sizes that are not a power of +two. + +=item * Calls to C functions with aggregates passed or returned by +value. + +=item * Calls to ctype metamethods which are not plain functions. + +=item * ctype C<__newindex> tables and non-string lookups in ctype +C<__index> tables. + +=item * C for cdata types. + +=item * Calls to C, C and C. + +=back + +Other missing features: + +=over + +=item * Arithmetic for C numbers. + +=item * Passing structs by value to vararg C functions. + +=item * C++ exception interoperability does not extend to C functions +called via the FFI, if the call is compiled. + +=back + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_ffi_semantics.html +# 53847 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/ext_ffi_tutorial.pod b/doc/LuaJIT-2.1/ext_ffi_tutorial.pod new file mode 100644 index 0000000..75c9eab --- /dev/null +++ b/doc/LuaJIT-2.1/ext_ffi_tutorial.pod @@ -0,0 +1,640 @@ +=pod + +LuaJIT + +=head1 FFI Tutorial + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +This page is intended to give you an overview of the features of the +FFI library by presenting a few use cases and guidelines. + +This page makes no attempt to explain all of the FFI library, though. +You'll want to have a look at the ffi.* API function reference and the +FFI semantics to learn more. + +=head2 Loading the FFI Library + +The FFI library is built into LuaJIT by default, but it's not loaded +and initialized by default. The suggested way to use the FFI library is +to add the following to the start of every Lua file that needs one of +its functions: + + local ffi = require("ffi") + +Please note this doesn't define an C variable in the table of +globals E you really need to use the local variable. The +C function ensures the library is only loaded once. + +Note: If you want to experiment with the FFI from the interactive +prompt of the command line executable, omit the C, as it doesn't +preserve local variables across lines. + +=head2 Accessing Standard System Functions + +The following code explains how to access standard system functions. We +slowly print two lines of dots by sleeping for 10 milliseconds after +each dot: + +   + ① + + + + + + ② + ③ + ④ + + + + ⑤ + + + + + + ⑥local ffi = require("ffi") + ffi.cdef[[ + void Sleep(int ms); + int poll(struct pollfd *fds, unsigned long nfds, int timeout); + ]] + + local sleep + if ffi.os == "Windows" then + function sleep(s) + ffi.C.Sleep(s*1000) + end + else + function sleep(s) + ffi.C.poll(nil, 0, s*1000) + end + end + + for i=1,160 do + io.write("."); io.flush() + sleep(0.01) + end + io.write("\n") + +Here's the step-by-step explanation: + +This defines the C library functions we're going to use. The part +inside the double-brackets (in green) is just standard C syntax. You +can usually get this info from the C header files or the documentation +provided by each C library or C compiler. + +The difficulty we're facing here, is that there are different standards +to choose from. Windows has a simple C function. On other +systems there are a variety of functions available to achieve +sub-second sleeps, but with no clear consensus. Thankfully C +can be used for this task, too, and it's present on most non-Windows +systems. The check for C makes sure we use the Windows-specific +function only on Windows systems. + +Here we're wrapping the call to the C function in a Lua function. This +isn't strictly necessary, but it's helpful to deal with system-specific +issues only in one part of the code. The way we're wrapping it ensures +the check for the OS is only done during initialization and not for +every call. + +A more subtle point is that we defined our C function (for the +sake of this example) as taking the number of seconds, but accepting +fractional seconds. Multiplying this by 1000 gets us milliseconds, but +that still leaves it a Lua number, which is a floating-point value. +Alas, the C function only accepts an integer value. Luckily +for us, the FFI library automatically performs the conversion when +calling the function (truncating the FP value towards zero, like in C). + +Some readers will notice that C is part of C and +is also a C function. So how can this possibly work? The FFI +library provides the C default C library namespace, which allows +calling functions from the default set of libraries, like a C compiler +would. Also, the FFI library automatically detects C +functions, so you don't need to declare them as such. + +The C function takes a couple more arguments we're not going to +use. You can simply use C to pass a C pointer and C<0> for +the C parameter. Please note that the number C<0> I, unlike in C++. You really have to pass +pointers to pointer arguments and numbers to number arguments. + +The page on FFI semantics has all of the gory details about conversions +between Lua objects and C types. For the most part you don't have to +deal with this, as it's performed automatically and it's carefully +designed to bridge the semantic differences between Lua and C. + +Now that we have defined our own C function, we can just call +it from plain Lua code. That wasn't so bad, huh? Turning these boring +animated dots into a fascinating best-selling game is left as an +exercise for the reader. :-) + +=head2 Accessing the zlib Compression Library + +The following code shows how to access the zlib compression library +from Lua code. We'll define two convenience wrapper functions that take +a string and compress or uncompress it to another string: + +   + ① + + + + + + + ② + + + ③ + + ④ + + + ⑤ + + + ⑥ + + + + + + + + ⑦local ffi = require("ffi") + ffi.cdef[[ + unsigned long compressBound(unsigned long sourceLen); + int compress2(uint8_t *dest, unsigned long *destLen, + const uint8_t *source, unsigned long sourceLen, int level); + int uncompress(uint8_t *dest, unsigned long *destLen, + const uint8_t *source, unsigned long sourceLen); + ]] + local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z") + + local function compress(txt) + local n = zlib.compressBound(#txt) + local buf = ffi.new("uint8_t[?]", n) + local buflen = ffi.new("unsigned long[1]", n) + local res = zlib.compress2(buf, buflen, txt, #txt, 9) + assert(res == 0) + return ffi.string(buf, buflen[0]) + end + + local function uncompress(comp, n) + local buf = ffi.new("uint8_t[?]", n) + local buflen = ffi.new("unsigned long[1]", n) + local res = zlib.uncompress(buf, buflen, comp, #comp) + assert(res == 0) + return ffi.string(buf, buflen[0]) + end + + -- Simple test code. + local txt = string.rep("abcd", 1000) + print("Uncompressed size: ", #txt) + local c = compress(txt) + print("Compressed size: ", #c) + local txt2 = uncompress(c, #txt) + assert(txt2 == txt) + +Here's the step-by-step explanation: + +This defines some of the C functions provided by zlib. For the sake of +this example, some type indirections have been reduced and it uses the +pre-defined fixed-size integer types, while still adhering to the zlib +API/ABI. + +This loads the zlib shared library. On POSIX systems it's named +C and usually comes pre-installed. Since C +automatically adds any missing standard prefixes/suffixes, we can +simply load the C<"z"> library. On Windows it's named C and +you'll have to download it first from the E zlib site. The +check for C makes sure we pass the right name to C. + +First, the maximum size of the compression buffer is obtained by +calling the C function with the length of the +uncompressed string. The next line allocates a byte buffer of this +size. The C<[?]> in the type specification indicates a variable-length +array (VLA). The actual number of elements of this array is given as +the 2nd argument to C. + +This may look strange at first, but have a look at the declaration of +the C function from zlib: the destination length is defined +as a pointer! This is because you pass in the maximum buffer size and +get back the actual length that was used. + +In C you'd pass in the address of a local variable (C<&buflen>). But +since there's no address-of operator in Lua, we'll just pass in a +one-element array. Conveniently it can be initialized with the maximum +buffer size in one step. Calling the actual C function +is then straightforward. + +We want to return the compressed data as a Lua string, so we'll use +C. It needs a pointer to the start of the data and the +actual length. The length has been returned in the C array, so +we'll just get it from there. + +Note that since the function returns now, the C and C +variables will eventually be garbage collected. This is fine, because +C has copied the contents to a newly created (interned) +Lua string. If you plan to call this function lots of times, consider +reusing the buffers and/or handing back the results in buffers instead +of strings. This will reduce the overhead for garbage collection and +string interning. + +The C functions does the exact opposite of the C +function. The compressed data doesn't include the size of the original +string, so this needs to be passed in. Otherwise no surprises here. + +The code, that makes use of the functions we just defined, is just +plain Lua code. It doesn't need to know anything about the LuaJIT FFI +E the convenience wrapper functions completely hide it. + +One major advantage of the LuaJIT FFI is that you are now able to write +those wrappers I. And at a fraction of the time it would cost +you to create an extra C module using the Lua/C API. Many of the +simpler C functions can probably be used directly from your Lua code, +without any wrappers. + +Side note: the zlib API uses the C type for passing lengths and +sizes around. But all those zlib functions actually only deal with 32 +bit values. This is an unfortunate choice for a public API, but may be +explained by zlib's history E we'll just have to deal with it. + +First, you should know that a C is a 64 bit type e.g. on +POSIX/x64 systems, but a 32 bit type on Windows/x64 and on 32 bit +systems. Thus a C result can be either a plain Lua number or a +boxed 64 bit integer cdata object, depending on the target system. + +Ok, so the C functions generally accept cdata objects wherever +you'd want to use a number. That's why we get a away with passing C +to C above. But other Lua library functions or modules +don't know how to deal with this. So for maximum portability one needs +to use C on returned C results before passing them +on. Otherwise the application might work on some systems, but would +fail in a POSIX/x64 environment. + +=head2 Defining Metamethods for a C Type + +The following code explains how to define metamethods for a C type. We +define a simple point type and add some operations to it: + +   + ① + + + + ② + + ③ + + ④ + + + + ⑤ + + ⑥local ffi = require("ffi") + ffi.cdef[[ + typedef struct { double x, y; } point_t; + ]] + + local point + local mt = { + __add = function(a, b) return point(a.x+b.x, a.y+b.y) end, + __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end, + __index = { + area = function(a) return a.x*a.x + a.y*a.y end, + }, + } + point = ffi.metatype("point_t", mt) + + local a = point(3, 4) + print(a.x, a.y) --> 3 4 + print(#a) --> 5 + print(a:area()) --> 25 + local b = a + point(0.5, 8) + print(#b) --> 12.5 + +Here's the step-by-step explanation: + +This defines the C type for a two-dimensional point object. + +We have to declare the variable holding the point constructor first, +because it's used inside of a metamethod. + +Let's define an C<__add> metamethod which adds the coordinates of two +points and creates a new point object. For simplicity, this function +assumes that both arguments are points. But it could be any mix of +objects, if at least one operand is of the required type (e.g. adding a +point plus a number or vice versa). Our C<__len> metamethod returns the +distance of a point to the origin. + +If we run out of operators, we can define named methods, too. Here the +C<__index> table defines an C function. For custom indexing +needs, one might want to define C<__index> and C<__newindex> +I instead. + +This associates the metamethods with our C type. This only needs to be +done once. For convenience, a constructor is returned by +C. We're not required to use it, though. The original C +type can still be used e.g. to create an array of points. The +metamethods automatically apply to any and all uses of this type. + +Please note that the association with a metatable is permanent and +B Ditto for the +C<__index> table. + +Here are some simple usage examples for the point type and their +expected results. The pre-defined operations (such as C) can be +freely mixed with the newly defined metamethods. Note that C is a +method and must be called with the Lua syntax for methods: C, +not C. + +The C type metamethod mechanism is most useful when used in conjunction +with C libraries that are written in an object-oriented style. Creators +return a pointer to a new instance and methods take an instance pointer +as the first argument. Sometimes you can just point C<__index> to the +library namespace and C<__gc> to the destructor and you're done. But +often enough you'll want to add convenience wrappers, e.g. to return +actual Lua strings or when returning multiple values. + +Some C libraries only declare instance pointers as an opaque C +type. In this case you can use a fake type for all declarations, e.g. a +pointer to a named (incomplete) struct will do: C. The C side doesn't know what you declare with +the LuaJIT FFI, but as long as the underlying types are compatible, +everything still works. + +=head2 Translating C Idioms + +Here's a list of common C idioms and their translation to the LuaJIT +FFI: + +Idiom + +C code + +Lua code + +Pointer dereference + +C + +x = *p; + +*p = y; + +x = B + +B = y + +Pointer indexing + +C + +x = p[i]; + +p[i+1] = y; + +x = p[i] + +p[i+1] = y + +Array indexing + +C + +x = a[i]; + +a[i+1] = y; + +x = a[i] + +a[i+1] = y + +C/C dereference + +C + +x = s.field; + +s.field = y; + +x = s.field + +s.field = y + +C/C pointer deref. + +C + +x = sp-Efield; + +sp-Efield = y; + +x = B + +B = y + +Pointer arithmetic + +C + +x = p + i; + +y = p - i; + +x = p + i + +y = p - i + +Pointer difference + +C + +C + +C + +Array element pointer + +C + +C + +C> + +Cast pointer to address + +C + +C + +x = tonumber( + +ffi.cast("intptr_t", + +p)) + +Functions with outargs + +C + +int len = x; + +foo(&len); + +y = len; + +local len = + +ffi.new("int[1]", x) + +foo(len) + +y = len[0] + +Vararg conversions + +C + +printf("%g", 1.0); + +printf("%d", 1); + +printf("%g", 1); + +printf("%d", + +B) + +=head2 To Cache or Not to Cache + +It's a common Lua idiom to cache library functions in local variables +or upvalues, e.g.: + + local byte, char = string.byte, string.char + local function foo(x) + return char(byte(x)+1) + end + +This replaces several hash-table lookups with a (faster) direct use of +a local or an upvalue. This is less important with LuaJIT, since the +JIT compiler optimizes hash-table lookups a lot and is even able to +hoist most of them out of the inner loops. It can't eliminate I of +them, though, and it saves some typing for often-used functions. So +there's still a place for this, even with LuaJIT. + +The situation is a bit different with C function calls via the FFI +library. The JIT compiler has special logic to eliminate I for functions resolved from a C library namespace! +Thus it's not helpful and actually counter-productive to cache +individual C functions like this: + + local funca, funcb = ffi.C.funca, ffi.C.funcb -- Not helpful! + local function foo(x, n) + for i=1,n do funcb(funca(x, i), 1) end + end + +This turns them into indirect calls and generates bigger and slower +machine code. Instead you'll want to cache the namespace itself and +rely on the JIT compiler to eliminate the lookups: + + local C = ffi.C -- Instead use this! + local function foo(x, n) + for i=1,n do C.funcb(C.funca(x, i), 1) end + end + +This generates both shorter and faster code. So B, but B cache namespaces! Most often the namespace is +already in a local variable at an outer scope, e.g. from C. Note that copying it to a local variable in the +function scope is unnecessary. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_ffi_tutorial.html +# 22557 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render +# Deleting phrasal "code" element (`tt_100) because it has super-phrasal elements (`br_33, `br_34) as children. +# Deleting phrasal "code" element (`tt_99) because it has super-phrasal elements (`br_31, `br_32) as children. +# Deleting phrasal "b" element (`b_8) because it has super-phrasal elements (`br_27, `br_28, `br_29) as children. +# Deleting phrasal "code" element (`tt_97) because it has super-phrasal elements (`br_27, `br_28, `br_29) as children. +# Deleting phrasal "code" element (`tt_96) because it has super-phrasal elements (`br_25, `br_26) as children. +# Deleting phrasal "b" element (`b_7) because it has super-phrasal elements (`br_22, `br_23) as children. +# Deleting phrasal "code" element (`tt_94) because it has super-phrasal elements (`br_22, `br_23) as children. +# Deleting phrasal "code" element (`tt_85) because it has super-phrasal elements (`br_18) as children. +# Deleting phrasal "code" element (`tt_84) because it has super-phrasal elements (`br_17) as children. +# Deleting phrasal "code" element (`tt_82) because it has super-phrasal elements (`br_15) as children. +# Deleting phrasal "code" element (`tt_81) because it has super-phrasal elements (`br_14) as children. +# Deleting phrasal "code" element (`tt_77) because it has super-phrasal elements (`br_12) as children. +# Deleting phrasal "code" element (`tt_76) because it has super-phrasal elements (`br_11) as children. +# Deleting phrasal "code" element (`tt_72) because it has super-phrasal elements (`br_9) as children. +# Deleting phrasal "code" element (`tt_71) because it has super-phrasal elements (`br_8) as children. +# Deleting phrasal "code" element (`tt_69) because it has super-phrasal elements (`br_6) as children. +# Deleting phrasal "code" element (`tt_68) because it has super-phrasal elements (`br_5) as children. +# Deleting phrasal "code" element (`tt_66) because it has super-phrasal elements (`br_3) as children. +# Deleting phrasal "code" element (`tt_65) because it has super-phrasal elements (`br_2) as children. diff --git a/doc/LuaJIT-2.1/ext_jit.pod b/doc/LuaJIT-2.1/ext_jit.pod new file mode 100644 index 0000000..8741627 --- /dev/null +++ b/doc/LuaJIT-2.1/ext_jit.pod @@ -0,0 +1,182 @@ +=pod + +LuaJIT + +=head1 C Library + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +The functions in this built-in module control the behavior of the JIT +compiler engine. Note that JIT-compilation is fully automatic E +you probably won't need to use any of the following functions unless +you have special needs. + +=head2 jit.on() + +jit.off() + +Turns the whole JIT compiler on (default) or off. + +These functions are typically used with the command line options C<-j +on> or C<-j off>. + +=head2 C + +Flushes the whole cache of compiled code. + +=head2 jit.on(func|true [,true|false]) + +jit.off(func|true [,true|false]) + +jit.flush(func|true [,true|false]) + +C enables JIT compilation for a Lua function (this is the +default). + +C disables JIT compilation for a Lua function and flushes any +already compiled code from the code cache. + +C flushes the code, but doesn't affect the enable/disable +status. + +The current function, i.e. the Lua function calling this library +function, can also be specified by passing C as the first +argument. + +If the second argument is C, JIT compilation is also enabled, +disabled or flushed recursively for all sub-functions of a function. +With C only the sub-functions are affected. + +The C and C functions only set a flag which is checked +when the function is about to be compiled. They do not trigger +immediate compilation. + +Typical usage is C in the main chunk of a module +to turn off JIT compilation for the whole module for debugging +purposes. + +=head2 C + +Flushes the root trace, specified by its number, 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. + +=head2 C + +Returns the current status of the JIT compiler. The first result is +either C or C if the JIT compiler is turned on or off. The +remaining results are strings for CPU-specific features and enabled +optimizations. + +=head2 C + +Contains the LuaJIT version string. + +=head2 C + +Contains the version number of the LuaJIT core. Version xx.yy.zz is +represented by the decimal number xxyyzz. + +=head2 C + +Contains the target OS name: "Windows", "Linux", "OSX", "BSD", "POSIX" +or "Other". + +=head2 C + +Contains the target architecture name: "x86", "x64", "arm", "arm64", +"ppc", "mips" or "mips64". + +=head2 C E JIT compiler optimization control + +This sub-module provides the backend for the C<-O> command line option. + +You can also use it programmatically, e.g.: + + jit.opt.start(2) -- same as -O2 + jit.opt.start("-dce") + jit.opt.start("hotloop=10", "hotexit=2") + +Unlike in LuaJIT 1.x, the module is built-in and B It's no longer necessary to run +C, which was one of the ways to enable +optimization. + +=head2 C E JIT compiler introspection + +This sub-module holds functions to introspect the bytecode, generated +traces, the IR and the generated machine code. The functionality +provided by this module is still in flux and therefore undocumented. + +The debug modules C<-jbc>, C<-jv> and C<-jdump> make extensive use of +these functions. Please check out their source code, if you want to +know more. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_jit.html +# 5903 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render +# Deleting phrasal "code" element (`tt_6) because it has super-phrasal elements (`br_2, `br_3) as children. +# Deleting phrasal "code" element (`tt_2) because it has super-phrasal elements (`br_1) as children. diff --git a/doc/LuaJIT-2.1/ext_profiler.pod b/doc/LuaJIT-2.1/ext_profiler.pod new file mode 100644 index 0000000..fa1a7da --- /dev/null +++ b/doc/LuaJIT-2.1/ext_profiler.pod @@ -0,0 +1,358 @@ +=pod + +LuaJIT + +=head1 Profiler + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT has an integrated statistical profiler with very low overhead. +It allows sampling the currently executing stack and other parameters +in regular intervals. + +The integrated profiler can be accessed from three levels: + +=over + +=item * The bundled high-level profiler, invoked by the C<-jp> command +line option. + +=item * A low-level Lua API to control the profiler. + +=item * A low-level C API to control the profiler. + +=back + +=head2 High-Level Profiler + +The bundled high-level profiler offers basic profiling functionality. +It generates simple textual summaries or source code annotations. It +can be accessed with the C<-jp> command line option or from Lua code by +loading the underlying C module. + +To cut to the chase E run this to get a CPU usage profile by +function name: + + luajit -jp myapp.lua + +It's I a stated goal of the bundled profiler to add every possible +option or to cater for special profiling needs. The low-level profiler +APIs are documented below. They may be used by third-party authors to +implement advanced functionality, e.g. IDE integration or graphical +profilers. + +Note: Sampling works for both interpreted and JIT-compiled code. The +results for JIT-compiled code may sometimes be surprising. LuaJIT +heavily optimizes and inlines Lua code E there's no simple +one-to-one correspondence between source code lines and the sampled +machine code. + +=head2 C<-jp=[options[,output]]> + +The C<-jp> command line option starts the high-level profiler. When the +application run by the command line terminates, the profiler stops and +writes the results to C or to the specified C file. + +The C argument specifies how the profiling is to be performed: + +=over + +=item * C E Stack dump: function name, otherwise module:line. +This is the default mode. + +=item * C E Stack dump: ditto, but dump module:name. + +=item * C E Stack dump: module:line. + +=item * CnumberE> E stack dump depth (callee E +caller). Default: 1. + +=item * C<-EnumberE> E Inverse stack dump depth (caller +E callee). + +=item * C E Split stack dump after first stack level. Implies +depth E 2 or depth E -2. + +=item * C

E Preserve the full path for module names. +Otherwise only the file name is used. + +=item * C E Dump the function name if it can be derived. +Otherwise use module:line. + +=item * C E Ditto, but dump module:name. + +=item * C E Dump module:line. + +=item * C E Zap the following characters for the last dumped +frame. + +=item * All other characters are added verbatim to the output string. + +=back + +The C argument gives the number of frames to dump, starting at +the topmost frame of the thread. A negative number dumps the frames in +inverse order. + +The first example prints a list of the current module names and line +numbers of up to 10 frames in separate lines. The second example prints +semicolon-separated function names for all frames (up to 100) in +inverse order: + + print(profile.dumpstack(thread, "l\n", 10)) + print(profile.dumpstack(thread, "lZ;", -100)) + +=head2 Low-level C API + +The profiler can be controlled directly from C code, e.g. for use by +IDEs. The declarations are in C<"luajit.h"> (see Lua/C API extensions). + +=head2 C E Start +profiler + +This function starts the profiler. See above for a description of the +C argument. + +The C argument is a callback function with the following +declaration: + + typedef void (*luaJIT_profile_callback)(void *data, lua_State *L, + int samples, int vmstate); + +C is available for use by the callback. C is the state that +holds the stack to sample for profiling. Note: do I modify this +stack or call functions on this stack E use a separate coroutine +for this purpose. See above for a description of C and +C. + +=head2 C E Stop profiler + +This function stops the profiler. + +=head2 C

E +Dump stack + +This function allows taking stack dumps in an efficient manner. See +above for a description of C and C. + +This function returns a C pointing to a private string +buffer of the profiler. The C argument returns the length of +the output string. The buffer is overwritten on the next call and +deallocated when the profiler stops. You either need to consume the +content immediately or copy it for later use. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file ext_profiler.html +# 13135 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/extensions.pod b/doc/LuaJIT-2.1/extensions.pod new file mode 100644 index 0000000..7eb8e3d --- /dev/null +++ b/doc/LuaJIT-2.1/extensions.pod @@ -0,0 +1,453 @@ +=pod + +LuaJIT + +=head1 Extensions + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT is fully upwards-compatible with Lua 5.1. It supports all +E standard Lua library functions and the full set of +E Lua/C API functions. + +LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic +loader level. This means you can compile a C module against the +standard Lua headers and load the same shared library from either Lua +or LuaJIT. + +LuaJIT extends the standard Lua VM with new functionality and adds +several extension modules. Please note this page is only about +I enhancements and not about performance enhancements, such +as the optimized VM, the faster interpreter or the JIT compiler. + +=head2 Extensions Modules + +LuaJIT comes with several built-in extension modules: + +=head2 C E Bitwise operations + +LuaJIT supports all bitwise operations as defined by E Lua +BitOp: + + bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor + bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap + +This module is a LuaJIT built-in E you don't need to download or +install Lua BitOp. The Lua BitOp site has full documentation for all +E Lua BitOp API functions. The FFI adds support for 64 bit +bitwise operations, using the same API functions. + +Please make sure to C the module before using any of its +functions: + + local bit = require("bit") + +An already installed Lua BitOp module is ignored by LuaJIT. This way +you can use bit operations from both Lua and LuaJIT on a shared +installation. + +=head2 C E FFI library + +The FFI library allows calling external C functions and the use of C +data structures from pure Lua code. + +=head2 C E JIT compiler control + +The functions in this module control the behavior of the JIT compiler +engine. + +=head2 C API extensions + +LuaJIT adds some extra functions to the Lua/C API. + +=head2 Profiler + +LuaJIT has an integrated profiler. + +=head2 Enhanced Standard Library Functions + +=head2 C passes arguments + +Unlike the standard implementation in Lua 5.1, C passes any +arguments after the error function to the function which is called in a +protected context. + +=head2 C etc. handle UTF-8 source code + +Non-ASCII characters are handled transparently by the Lua source code +parser. This allows the use of UTF-8 characters in identifiers and +strings. A UTF-8 BOM is skipped at the start of the source code. + +=head2 C etc. canonicalize NaN and EInf + +All number-to-string conversions consistently convert non-finite +numbers to the same strings on all platforms. NaN results in C<"nan">, +positive infinity results in C<"inf"> and negative infinity results in +C<"-inf">. + +=head2 C etc. use builtin string to number conversion + +All string-to-number conversions consistently convert integer and +floating-point inputs in decimal, hexadecimal and binary on all +platforms. C is I used anymore, which avoids numerous +problems with poor C library implementations. The builtin conversion +function provides full precision according to the IEEE-754 standard, it +works independently of the current locale and it supports hex +floating-point numbers (e.g. C<0x1.5p-3>). + +=head2 C generates portable bytecode + +An extra argument has been added to C. If set to +C, 'stripped' bytecode without debug information is generated. +This speeds up later bytecode loading and reduces memory usage. See +also the C<-b> command line option. + +The generated bytecode is portable and can be loaded on any +architecture that LuaJIT supports, independent of word size or +endianess. However the bytecode compatibility versions must match. +Bytecode stays compatible for dot releases (x.y.0 E x.y.1), but +may change with major or minor releases (2.0 E 2.1) or between +any beta release. Foreign bytecode (e.g. from Lua 5.1) is incompatible +and cannot be loaded. + +Note: C mode requires a different frame layout, which implies +a different, incompatible bytecode format for ports that use this mode +(e.g. ARM64). This may be rectified in the future. + +=head2 C allocates a pre-sized table + +An extra library function C can be made available via +C. This creates a pre-sized table, just like the +C API equivalent C. This is useful for big tables if +the final table size is known and automatic table resizing is too +expensive. + +=head2 C clears a table + +An extra library function C can be made available via +C. This clears all keys and values from a +table, but preserves the allocated array/hash sizes. This is useful +when a table, which is linked from multiple places, needs to be cleared +and/or when recycling a table for use by the same context. This avoids +managing backlinks, saves an allocation and the overhead of incremental +array/hash part growth. + +Please note this function is meant for very specific situations. In +most cases it's better to replace the (usually single) link with a new +table and let the GC do its work. + +=head2 Enhanced PRNG for C + +LuaJIT uses a Tausworthe PRNG with period 2^223 to implement +C and C. The quality of the PRNG +results is much superior compared to the standard Lua implementation +which uses the platform-specific ANSI rand(). + +The PRNG generates the same sequences from the same seeds on all +platforms and makes use of all bits in the seed argument. +C without arguments generates 52 pseudo-random bits for +every call. The result is uniformly distributed between 0.0 and 1.0. +It's correctly scaled up and rounded for C to +preserve uniformity. + +=head2 C functions handle 64 bit file offsets + +The file I/O functions in the standard C library handle 64 bit +file offsets. In particular this means it's possible to open files +larger than 2 Gigabytes and to reposition or obtain the current file +position for offsets beyond 2 GB (C method). + +=head2 C functions identify metamethods + +C and C also return information about +invoked metamethods. The C field is set to C<"metamethod"> +and the C field has the name of the corresponding metamethod +(e.g. C<"__index">). + +=head2 Fully Resumable VM + +The LuaJIT VM is fully resumable. This means you can yield from a +coroutine even across contexts, where this would not possible with the +standard Lua 5.1 VM: e.g. you can yield across C and +C, across iterators and across metamethods. + +=head2 Extensions from Lua 5.2 + +LuaJIT supports some language and library extensions from Lua 5.2. +Features that are unlikely to break existing code are unconditionally +enabled: + +=over + +=item * C and C<::labels::>. + +=item * Hex escapes C<'\x3F'> and C<'\*'> escape in strings. + +=item * C. + +=item * C is an alias for C. + +=item * C. + +=item * C. + +=item * C. + +=item * C: C<%q> reversible. C<%s> checks +C<__tostring>. C<%a> and C<"%A> added. + +=item * String matching pattern C<%g> added. + +=item * C. + +=item * C and C process C options. + +=item * C. + +=item * C. + +=item * C. + +=item * C returns C and C for +option C<"u">. + +=item * C accepts function instead of level. + +=item * C and C accept negative +indexes for varargs. + +=item * C and C handle C +functions. + +=item * C and C. + +=item * Command line option C<-E>. + +=item * Command line checks C<__tostring> for errors. + +=back + +Other features are only enabled, if LuaJIT is built with +C<-DLUAJIT_ENABLE_LUA52COMPAT>: + +=over + +=item * C is a keyword and not a valid variable name anymore. + +=item * C can be placed anywhere. Empty statements (C<;;>) are +allowed. + +=item * C<__lt>, C<__le> are invoked for mixed types. + +=item * C<__len> for tables. C library function. + +=item * C and C check for C<__pairs> and +C<__ipairs>. + +=item * C returns two results. + +=item * C and C (same as C). + +=item * C and C return file handle instead of +C. + +=item * C and C return detailed exit +status. + +=item * C returns object. + +=item * C and C. + +=item * Remove C, C. + +=back + +Note: this provides only partial compatibility with Lua 5.2 at the +language and Lua library level. LuaJIT is API+ABI-compatible with Lua +5.1, which prevents implementing features that would otherwise break +the Lua/C API and ABI (e.g. C<_ENV>). + +=head2 Extensions from Lua 5.3 + +LuaJIT supports some extensions from Lua 5.3: + +=over + +=item * Unicode escape C<'\u{XX...}'> embeds the UTF-8 encoding in +string literals. + +=back + +=head2 C++ Exception Interoperability + +LuaJIT has built-in support for interoperating with C++ exceptions. The +available range of features depends on the target platform and the +toolchain used to compile LuaJIT: + +Platform + +Compiler + +Interoperability + +POSIX/x64, DWARF2 unwinding + +GCC 4.3+, Clang + +B + +ARM C<-DLUAJIT_UNWIND_EXTERNAL> + +GCC, Clang + +B + +Other platforms, DWARF2 unwinding + +GCC, Clang + +B + +Windows/x64 + +MSVC or WinSDK + +B + +Windows/x86 + +Any + +B + +Other platforms + +Other compilers + +B + +B means: + +=over + +=item * C++ exceptions can be caught on the Lua side with C, +C etc. + +=item * C++ exceptions will be converted to the generic Lua error +C<"C++ exception">, unless you use the C call wrapper feature. + +=item * It's safe to throw C++ exceptions across non-protected Lua +frames on the C stack. The contents of the C++ exception object pass +through unmodified. + +=item * Lua errors can be caught on the C++ side with C. +The corresponding Lua error message can be retrieved from the Lua +stack. + +=item * Throwing Lua errors across C++ frames is safe. C++ destructors +will be called. + +=back + +B means: + +=over + +=item * C++ exceptions can be caught on the Lua side with C, +C etc. + +=item * C++ exceptions will be converted to the generic Lua error +C<"C++ exception">, unless you use the C call wrapper feature. + +=item * C++ exceptions will be caught by non-protected Lua frames and +are rethrown as a generic Lua error. The C++ exception object will be +destroyed. + +=item * Lua errors B be caught on the C++ side. + +=item * Throwing Lua errors across C++ frames will B call C++ +destructors. + +=back + +B means: + +=over + +=item * It's B safe to throw C++ exceptions across Lua frames. + +=item * C++ exceptions B be caught on the Lua side. + +=item * Lua errors B be caught on the C++ side. + +=item * Throwing Lua errors across C++ frames will B call C++ +destructors. + +=back + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file extensions.html +# 16722 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/faq.pod b/doc/LuaJIT-2.1/faq.pod new file mode 100644 index 0000000..360f46a --- /dev/null +++ b/doc/LuaJIT-2.1/faq.pod @@ -0,0 +1,224 @@ +=pod + +LuaJIT + +=head1 Frequently Asked Questions (FAQ) + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +=over + +=item Q: Where can I learn more about LuaJIT and Lua? + +=over + +=item * The E LuaJIT mailing list focuses on topics related +to LuaJIT. + +=item * The E LuaJIT wiki gathers community resources about +LuaJIT. + +=item * News about Lua itself can be found at the E Lua +mailing list. The mailing list archives are worth checking out for +older postings about LuaJIT. + +=item * The E main Lua.org site has complete E +documentation of the language and links to books and papers about Lua. + +=item * The community-managed E Lua Wiki has information +about diverse topics. + +=back + +=back + +=over + +=item Q: Where can I learn more about the compiler technology used by +LuaJIT? + +I'm planning to write more documentation about the internals of LuaJIT. +In the meantime, please use the following Google Scholar searches to +find relevant papers: + +Search for: E Trace Compiler + +Search for: E JIT Compiler + +Search for: E Dynamic Language Optimizations + +Search for: E SSA Form + +Search for: E Linear Scan Register Allocation + +Here is a list of the E innovative features in LuaJIT. + +And, you know, reading the source is of course the only way to +enlightenment. :-) + +=back + +=over + +=item Q: Why do I get this error: "attempt to index global 'arg' (a nil +value)"? + +Q: My vararg functions fail after switching to LuaJIT! + +LuaJIT is compatible to the Lua 5.1 language standard. It doesn't +support the implicit C parameter for old-style vararg functions +from Lua 5.0. + +Please convert your code to the E Lua 5.1 vararg syntax. + +=back + +=over + +=item Q: Why do I get this error: "bad FPU precision"? + +=item Q: I get weird behavior after initializing Direct3D. + +=item Q: Some FPU operations crash after I load a Delphi DLL. + +DirectX/Direct3D (up to version 9) sets the x87 FPU to single-precision +mode by default. This violates the Windows ABI and interferes with the +operation of many programs E LuaJIT is affected, too. Please +make sure you always use the C flag when +initializing Direct3D. + +Direct3D version 10 or higher do not show this behavior anymore. +Consider testing your application with older versions, too. + +Similarly, the Borland/Delphi runtime modifies the FPU control word and +enables FP exceptions. Of course this violates the Windows ABI, too. +Please check the Delphi docs for the Set8087CW method. + +=back + +=over + +=item Q: Sometimes Ctrl-C fails to stop my Lua program. Why? + +The interrupt signal handler sets a Lua debug hook. But this is +currently ignored by compiled code (this will eventually be fixed). If +your program is running in a tight loop and never falls back to the +interpreter, the debug hook never runs and can't throw the +"interrupted!" error. + +In the meantime you have to press Ctrl-C twice to get stop your +program. That's similar to when it's stuck running inside a C function +under the Lua interpreter. + +=back + +=over + +=item Q: Why doesn't my favorite power-patch for Lua apply against +LuaJIT? + +Because it's a completely redesigned VM and has very little code in +common with Lua anymore. Also, if the patch introduces changes to the +Lua semantics, these would need to be reflected everywhere in the VM, +from the interpreter up to all stages of the compiler. + +Please use only standard Lua language constructs. For many common needs +you can use source transformations or use wrapper or proxy functions. +The compiler will happily optimize away such indirections. + +=back + +=over + +=item Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU? + +Because it's a compiler E it needs to generate native machine +code. This means the code generator must be ported to each +architecture. And the fast interpreter is written in assembler and must +be ported, too. This is quite an undertaking. + +The install documentation shows the supported architectures. Other +architectures will follow based on sufficient user demand and/or +sponsoring. + +=back + +=over + +=item Q: When will feature X be added? When will the next version be +released? + +When it's ready. + +C'mon, it's open source E I'm doing it on my own time and you're +getting it for free. You can either contribute a patch or sponsor the +development of certain features, if they are important to you. + +=back + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file faq.html +# 7685 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/install.pod b/doc/LuaJIT-2.1/install.pod new file mode 100644 index 0000000..1df455e --- /dev/null +++ b/doc/LuaJIT-2.1/install.pod @@ -0,0 +1,698 @@ +=pod + +LuaJIT + +=head1 Installation + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT is only distributed as a source package. This page explains how +to build and install LuaJIT with different operating systems and C +compilers. + +For the impatient (on POSIX systems): + + make && sudo make install + +LuaJIT currently builds out-of-the box on most systems. Here's the +compatibility matrix for the supported combinations of operating +systems, CPUs and compilers: + +CPU / OS + +Linux or + +Android + +*BSD, Other + +OSX 10.4+ or + +iOS 3.0+ + +Windows + +XP/Vista/7 + +x86 (32 bit) + +GCC 4.2+ + +GCC 4.2+ + +XCode 5.0+ + +Clang + +MSVC, MSVC/EE + +WinSDK + +MinGW, Cygwin + +x64 (64 bit) + +GCC 4.2+ + +GCC 4.2+ + +ORBIS (PS4) + +XCode 5.0+ + +Clang + +MSVC + SDK v7.0 + +WinSDK v7.0 + +Durango (Xbox One) + +ARMv5+ + +ARM9E+ + +GCC 4.2+ + +GCC 4.2+ + +PSP2 (PS VITA) + +XCode 5.0+ + +Clang + +ARM64 + +GCC 4.8+ + +XCode 6.0+ + +Clang 3.5+ + +PPC + +GCC 4.3+ + +GCC 4.3+ + +GCC 4.1 (PS3) + +XEDK (Xbox 360) + +MIPS32 + +MIPS64 + +GCC 4.3+ + +GCC 4.3+ + +=head2 Configuring LuaJIT + +The standard configuration should work fine for most installations. +Usually there is no need to tweak the settings. The following files +hold all user-configurable settings: + +=over + +=item * C sets some configuration variables. + +=item * C has settings for B LuaJIT (POSIX only). + +=item * C has settings for B LuaJIT under +POSIX, MinGW or Cygwin. + +=item * C has settings for compiling LuaJIT with +MSVC or WinSDK. + +=back + +Please read the instructions given in these files, before changing any +settings. + +=head2 POSIX Systems (Linux, OSX, *BSD etc.) + +=head2 Prerequisites + +Depending on your distribution, you may need to install a package for +GCC, the development headers and/or a complete SDK. E.g. on a current +Debian/Ubuntu, install C with the package manager. + +Download the current source package of LuaJIT (pick the .tar.gz), if +you haven't already done so. Move it to a directory of your choice, +open a terminal window and change to this directory. Now unpack the +archive and change to the newly created directory: + + tar zxf LuaJIT-2.0.4.tar.gz + cd LuaJIT-2.0.4 + +=head2 Building LuaJIT + +The supplied Makefiles try to auto-detect the settings needed for your +operating system and your compiler. They need to be run with GNU Make, +which is probably the default on your system, anyway. Simply run: + + make + +This always builds a native binary, depending on the host OS you're +running this command on. Check the section on cross-compilation for +more options. + +By default, modules are only searched under the prefix C. +You can add an extra prefix to the search paths by appending the +C option, e.g.: + + make PREFIX=/home/myself/lj2 + +Note for OSX: if the C environment variable +is not set, then it's forced to C<10.4>. + +=head2 Installing LuaJIT + +The top-level Makefile installs LuaJIT by default under C, +i.e. the executable ends up in C and so on. You need +root privileges to write to this path. So, assuming sudo is installed +on your system, run the following command and enter your sudo password: + + sudo make install + +Otherwise specify the directory prefix as an absolute path, e.g.: + + make install PREFIX=/home/myself/lj2 + +Obviously the prefixes given during build and installation need to be +the same. + +=head2 Windows Systems + +=head2 Prerequisites + +Either install one of the open source SDKs (E MinGW or +E Cygwin), which come with a modified GCC plus the required +development headers. + +Or install Microsoft's Visual C++ (MSVC). The freely downloadable +E Express Edition works just fine, but only contains an x86 +compiler. + +The freely downloadable E Windows SDK only comes with command +line tools, but this is all you need to build LuaJIT. It contains x86 +and x64 compilers. + +Next, download the source package and unpack it using an archive +manager (e.g. the Windows Explorer) to a directory of your choice. + +=head2 Building with MSVC + +Open a "Visual Studio .NET Command Prompt", C to the directory +where you've unpacked the sources and run these commands: + + cd src + msvcbuild + +Then follow the installation instructions below. + +=head2 Building with the Windows SDK + +Open a "Windows SDK Command Shell" and select the x86 compiler: + + setenv /release /x86 + +Or select the x64 compiler: + + setenv /release /x64 + +Then C to the directory where you've unpacked the sources and run +these commands: + + cd src + msvcbuild + +Then follow the installation instructions below. + +=head2 Building with MinGW or Cygwin + +Open a command prompt window and make sure the MinGW or Cygwin programs +are in your path. Then C to the directory where you've unpacked the +sources and run this command for MinGW: + + mingw32-make + +Or this command for Cygwin: + + make + +Then follow the installation instructions below. + +=head2 Installing LuaJIT + +Copy C and C (built in the C directory) to +a newly created directory (any location is ok). Add C and +C directories below it and copy all Lua files from the +C directory of the distribution to the latter directory. + +There are no hardcoded absolute path names E all modules are +loaded relative to the directory where C is installed (see +C). + +=head2 Cross-compiling LuaJIT + +First, let's clear up some terminology: + +=over + +=item * Host: This is your development system, usually based on a x64 +or x86 CPU. + +=item * Target: This is the target system you want LuaJIT to run on, +e.g. Android/ARM. + +=item * Toolchain: This comprises a C compiler, linker, assembler and a +matching C library. + +=item * Host (or system) toolchain: This is the toolchain used to build +native binaries for your host system. + +=item * Cross-compile toolchain: This is the toolchain used to build +binaries for the target system. They can only be run on the target +system. + +=back + +The GNU Makefile-based build system allows cross-compiling on any host +for any supported target: + +=over + +=item * Yes, you need a toolchain for both your host I your +target! + +=item * Both host and target architectures must have the same pointer +size. + +=item * E.g. if you want to cross-compile to a 32 bit target on a 64 +bit host, you need to install the multilib development package (e.g. +C on Debian/Ubuntu) and build a 32 bit host part +(C). + +=item * 64 bit targets always require compilation on a 64 bit host. + +=back + +You need to specify C whenever the host OS and the target +OS differ, or you'll get assembler or linker errors: + +=over + +=item * E.g. if you're compiling on a Windows or OSX host for embedded +Linux or Android, you need to add C to the examples +below. + +=item * For a minimal target OS, you may need to disable the built-in +allocator in C and use C. + +=item * Don't forget to specify the same C for the install +step, too. + +=back + +Here are some examples where host and target have the same CPU: + + # Cross-compile to a 32 bit binary on a multilib x64 OS + make CC="gcc -m32" + + # Cross-compile on Debian/Ubuntu for Windows (mingw32 package) + make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows + +The C prefix allows specifying a standard GNU cross-compile +toolchain (Binutils, GCC and a matching libc). The prefix may vary +depending on the C<--target> the toolchain was built for (note the +C prefix has a trailing C<"-">). The examples below use the +canonical toolchain triplets for Linux. + +Since there's often no easy way to detect CPU features at runtime, it's +important to compile with the proper CPU or architecture settings: + +=over + +=item * The best way to get consistent results is to specify the +correct settings when building the toolchain yourself. + +=item * For a pre-built, generic toolchain add C<-mcpu=...> or +C<-march=...> and other necessary flags to C. + +=item * For ARM it's important to have the correct C<-mfloat-abi=...> +setting, too. Otherwise LuaJIT may not run at the full performance of +your target CPU. + +=item * For MIPS it's important to select a supported ABI (o32 on +MIPS32, n64 on MIPS64) and consistently compile your project either +with hard-float or soft-float compiler settings. + +=back + +Here are some examples for targets with a different CPU than the host: + + # ARM soft-float + make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mfloat-abi=soft" + + # ARM soft-float ABI with VFP (example for Cortex-A9) + make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp" + + # ARM hard-float ABI with VFP (armhf, most modern toolchains) + make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- + + # ARM64 + make CROSS=aarch64-linux- + + # PPC + make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- + + # MIPS32 big-endian + make HOST_CC="gcc -m32" CROSS=mips-linux- + # MIPS32 little-endian + make HOST_CC="gcc -m32" CROSS=mipsel-linux- + + # MIPS64 big-endian + make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" + # MIPS64 little-endian + make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" + +You can cross-compile for B using the Android NDK. The +environment variables need to match the install locations and the +desired target platform. E.g. Android 4.0 corresponds to ABI level 14. +For details check the folder C in the NDK directory. + +Only a few common variations for the different CPUs, ABIs and platforms +are listed. Please use your own judgement for which combination you +want to build/deploy or which lowest common denominator you want to +pick: + + # Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo) + NDK=/opt/android/ndk + NDKABI=8 + NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9 + NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- + NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" + make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" + + # Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS) + NDK=/opt/android/ndk + NDKABI=14 + NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9 + NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- + NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" + NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8" + make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH" + + # Android/MIPS, mipsel (MIPS32R1 hard-float), Android 4.0+ (ICS) + NDK=/opt/android/ndk + NDKABI=14 + NDKVER=$NDK/toolchains/mipsel-linux-android-4.9 + NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android- + NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips" + make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" + + # Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS) + NDK=/opt/android/ndk + NDKABI=14 + NDKVER=$NDK/toolchains/x86-4.9 + NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android- + NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86" + make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" + +You can cross-compile for B (iPhone/iPad) using the +E iOS SDK: + +Note: B, because regular iOS Apps +are not allowed to generate code at runtime. You'll only get the +performance of the LuaJIT interpreter on iOS. This is still faster than +plain Lua, but much slower than the JIT compiler. Please complain to +Apple, not me. Or use Android. :-p + + # iOS/ARM (32 bit) + ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) + ICC=$(xcrun --sdk iphoneos --find clang) + ISDKF="-arch armv7 -isysroot $ISDKP" + make HOST_CC="clang -m32 -arch i386" CROSS="$(dirname $ICC)/" \ + TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS + + # iOS/ARM64 + ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) + ICC=$(xcrun --sdk iphoneos --find clang) + ISDKF="-arch arm64 -isysroot $ISDKP" + make CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS + +=head2 Cross-compiling for consoles + +Building LuaJIT for consoles requires both a supported host compiler +(x86 or x64) and a cross-compiler (to PPC or ARM) from the official +console SDK. + +Due to restrictions on consoles, the JIT compiler is disabled and only +the fast interpreter is built. This is still faster than plain Lua, but +much slower than the JIT compiler. The FFI is disabled, too, since it's +not very useful in such an environment. + +The following commands build a static library C, which can +be linked against your game, just like the Lua library. + +To cross-compile for B from a Linux host (requires 32 bit GCC, +i.e. multilib Linux/x64) or a Windows host (requires 32 bit MinGW), run +this command: + + make HOST_CC="gcc -m32" CROSS=ppu-lv2- + +To cross-compile for B from a Windows host, open a "Visual Studio +.NET Command Prompt" (64 bit host compiler), C to the directory +where you've unpacked the sources and run the following commands: + + cd src + ps4build + +To cross-compile for B from a Windows host, open a "Visual +Studio .NET Command Prompt" (32 bit host compiler), C to the +directory where you've unpacked the sources and run the following +commands: + + cd src + psvitabuild + +To cross-compile for B from a Windows host, open a "Visual +Studio .NET Command Prompt" (32 bit host compiler), C to the +directory where you've unpacked the sources and run the following +commands: + + cd src + xedkbuild + +To cross-compile for B from a Windows host, open a "Visual +Studio .NET Command Prompt" (64 bit host compiler), C to the +directory where you've unpacked the sources and run the following +commands: + + cd src + xb1build + +=head2 Embedding LuaJIT + +LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua +into your application, you probably don't need to do anything to switch +to LuaJIT, except link with a different library: + +=over + +=item * It's strongly suggested to build LuaJIT separately using the +supplied build system. Please do I attempt to integrate the +individual source files into your build tree. You'll most likely get +the internal build dependencies wrong or mess up the compiler flags. +Treat LuaJIT like any other external library and link your application +with either the dynamic or static library, depending on your needs. + +=item * If you want to load C modules compiled for plain Lua with +C, you need to make sure the public symbols (e.g. +C) are exported, too: + +=over + +=item * On POSIX systems you can either link to the shared library or +link the static library into your application. In the latter case +you'll need to export all public symbols from your main executable +(e.g. C<-Wl,-E> on Linux) and add the external dependencies (e.g. C<-lm +-ldl> on Linux). + +=item * Since Windows symbols are bound to a specific DLL name, you +need to link to the C created by the LuaJIT build (do not +rename the DLL). You may link LuaJIT statically on Windows only if you +don't intend to load Lua/C modules at runtime. + +=back + +=item * If you're building a 64 bit application on OSX which links +directly or indirectly against LuaJIT, you need to link your main +executable with these flags: + + -pagezero_size 10000 -image_base 100000000 + +Also, it's recommended to C all (self-compiled) shared +libraries which are loaded at runtime on OSX/x64 (e.g. C extension +modules for Lua). See: C + +=back + +Additional hints for initializing LuaJIT using the C API functions: + +=over + +=item * Here's a E simple example for embedding Lua or LuaJIT +into your application. + +=item * Make sure you use C. Avoid using +C, since this uses the (slower) default memory allocator +from your system (no support for this on x64). + +=item * Make sure you use C and not the old Lua 5.0 +style of calling C etc. directly. + +=item * To change or extend the list of standard libraries to load, +copy C to your project and modify it accordingly. Make +sure the C library is loaded or the JIT compiler will not be +activated. + +=item * The C module for bitwise operations is already built-in. +There's no need to statically link E Lua BitOp to your +application. + +=back + +=head2 Hints for Distribution Maintainers + +The LuaJIT build system has extra provisions for the needs of most +POSIX-based distributions. If you're a package maintainer for a +distribution, I make use of these features and avoid patching, +subverting, autotoolizing or messing up the build system in unspeakable +ways. + +There should be absolutely no need to patch C or any of the +Makefiles. And please do not hand-pick files for your packages E +simply use whatever C creates. There's a reason for all +of the files I directories it creates. + +The build system uses GNU make and auto-detects most settings based on +the host you're building it on. This should work fine for native +builds, even when sandboxed. You may need to pass some of the following +flags to I the C and the C command lines for +a regular distribution build: + +=over + +=item * C overrides the installation path and should usually be +set to C. Setting this also changes the module paths and the +paths needed to locate the shared library. + +=item * C is an absolute path which allows you to install to a +shadow tree instead of the root tree of the build system. + +=item * C sets the architecture-specific library path +component for multilib systems. The default is C. + +=item * Have a look at the top-level C and C +for additional variables to tweak. The following variables I be +overridden, but it's I recommended, except for special needs like +cross-builds: C + +=back + +The build system has a special target for an amalgamated build, i.e. +C. This compiles the LuaJIT core as one huge C file and +allows GCC to generate faster and shorter code. Alas, this requires +lots of memory during the build. This may be a problem for some users, +that's why it's not enabled by default. But it shouldn't be a problem +for most build farms. It's recommended that binary distributions use +this target for their LuaJIT builds. + +The tl;dr version of the above: + + make amalg PREFIX=/usr && \ + make install PREFIX=/usr DESTDIR=/tmp/buildroot + +Finally, if you encounter any difficulties, please contact me first, +instead of releasing a broken package onto unsuspecting users. Because +they'll usually gonna complain to me (the upstream) and not you (the +package maintainer), anyway. + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file install.html +# 25008 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render +# Deleting phrasal "a" element (`a_34) because it has super-phrasal elements (`br_16) as children. +# Deleting phrasal "a" element (`a_28) because it has super-phrasal elements (`br_11) as children. +# Deleting phrasal "a" element (`a_25) because it has super-phrasal elements (`br_3) as children. diff --git a/doc/LuaJIT-2.1/running.pod b/doc/LuaJIT-2.1/running.pod new file mode 100644 index 0000000..9baa295 --- /dev/null +++ b/doc/LuaJIT-2.1/running.pod @@ -0,0 +1,421 @@ +=pod + +LuaJIT + +=head1 Running LuaJIT + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT has only a single stand-alone executable, called C on +POSIX systems or C on Windows. It can be used to run simple +Lua statements or whole Lua applications from the command line. It has +an interactive mode, too. + +=head2 Command Line Options + +The C stand-alone executable is just a slightly modified +version of the regular C stand-alone executable. It supports the +same basic options, too. C prints a short list of the +available options. Please have a look at the E Lua manual for +details. + +LuaJIT has some additional options: + +=head2 C<-b[options] input output> + +This option saves or lists bytecode. The following additional options +are accepted: + +=over + +=item * C<-l> E Only list bytecode. + +=item * C<-s> E Strip debug info (this is the default). + +=item * C<-g> E Keep debug info. + +=item * C<-n name> E Set module name (default: auto-detect from +input name) + +=item * C<-t type> E Set output file type (default: auto-detect +from output name). + +=item * C<-a arch> E Override architecture for object files +(default: native). + +=item * C<-o os> E Override OS for object files (default: +native). + +=item * C<-e chunk> E Use chunk string as input. + +=item * C<-> (a single minus sign) E Use stdin as input and/or +stdout as output. + +=back + +The output file type is auto-detected from the extension of the output +file name: + +=over + +=item * C E C source file, exported bytecode data. + +=item * C E C header file, static bytecode data. + +=item * C or C E Object file, exported bytecode data +(OS- and architecture-specific). + +=item * C or any other extension E Raw bytecode file +(portable). + +=back + +Notes: + +=over + +=item * See also string.dump() for information on bytecode portability +and compatibility. + +=item * A file in raw bytecode format is auto-detected and can be +loaded like any Lua source file. E.g. directly from the command line or +with C, C etc. + +=item * To statically embed the bytecode of a module in your +application, generate an object file and just link it with your +application. + +=item * On most ELF-based systems (e.g. Linux) you need to explicitly +export the global symbols when linking your application, e.g. with: +C<-Wl,-E> + +=item * C tries to load embedded bytecode data from exported +symbols (in C<*.exe> or C on Windows) and from shared +libraries in C. + +=back + +Typical usage examples: + + luajit -b test.lua test.out # Save bytecode to test.out + luajit -bg test.lua test.out # Keep debug info + luajit -be "print('hello world')" test.out # Save cmdline script + + luajit -bl test.lua # List to stdout + luajit -bl test.lua test.txt # List to test.txt + luajit -ble "print('hello world')" # List cmdline script + + luajit -b test.lua test.obj # Generate object file + # Link test.obj with your application and load it with require("test") + +=head2 C<-j cmd[=arg[,arg...]]> + +This option performs a LuaJIT control command or activates one of the +loadable extension modules. The command is first looked up in the +C library. If no matching function is found, a module named +CcmdE> is loaded and the C function of the +module is called with the specified arguments (if any). The space +between C<-j> and C is optional. + +Here are the available LuaJIT control commands: + +=over + +=item * C<-jon> E Turns the JIT compiler on (default). + +=item * C<-joff> E Turns the JIT compiler off (only use the +interpreter). + +=item * C<-jflush> E Flushes the whole cache of compiled code. + +=item * C<-jv> E Shows verbose information about the progress of +the JIT compiler. + +=item * C<-jdump> E Dumps the code and structures used in +various compiler stages. + +=item * C<-jp> E Start the integrated profiler. + +=back + +The C<-jv> and C<-jdump> commands are extension modules written in Lua. +They are mainly used for debugging the JIT compiler itself. For a +description of their options and output format, please read the comment +block at the start of their source. They can be found in the C +directory of the source distribution or installed under the C +directory. By default this is C on +POSIX systems. + +=head2 C<-O[level]> + +C<-O[+]flag> C<-O-flag> + +C<-Oparam=value> + +This options allows fine-tuned control of the optimizations used by the +JIT compiler. This is mainly intended for debugging LuaJIT itself. +Please note that the JIT compiler is extremely fast (we are talking +about the microsecond to millisecond range). Disabling optimizations +doesn't have any visible impact on its overhead, but usually generates +code that runs slower. + +The first form sets an optimization level E this enables a +specific mix of optimization flags. C<-O0> turns off all optimizations +and higher numbers enable more optimizations. Omitting the level (i.e. +just C<-O>) sets the default optimization level, which is C<-O3> in the +current version. + +The second form adds or removes individual optimization flags. The +third form sets a parameter for the VM or the JIT compiler to a +specific value. + +You can either use this option multiple times (like C<-Ocse -O-dce +-Ohotloop=10>) or separate several settings with a comma (like +C<-O+cse,-dce,hotloop=10>). The settings are applied from left to right +and later settings override earlier ones. You can freely mix the three +forms, but note that setting an optimization level overrides all +earlier flags. + +Here are the available flags and at what optimization levels they are +enabled: + +Flag + +-O1 + +-O2 + +-O3 + +fold + +E + +E + +E + +Constant Folding, Simplifications and Reassociation + +cse + +E + +E + +E + +Common-Subexpression Elimination + +dce + +E + +E + +E + +Dead-Code Elimination + +narrow + +E + +E + +Narrowing of numbers to integers + +loop + +E + +E + +Loop Optimizations (code hoisting) + +fwd + +E + +Load Forwarding (L2L) and Store Forwarding (S2L) + +dse + +E + +Dead-Store Elimination + +abc + +E + +Array Bounds Check Elimination + +sink + +E + +Allocation/Store Sinking + +fuse + +E + +Fusion of operands into instructions + +Here are the parameters and their default settings: + +Parameter + +Default + +maxtrace + +1000 + +Max. number of traces in the cache + +maxrecord + +4000 + +Max. number of recorded IR instructions + +maxirconst + +500 + +Max. number of IR constants of a trace + +maxside + +100 + +Max. number of side traces of a root trace + +maxsnap + +500 + +Max. number of snapshots for a trace + +hotloop + +56 + +Number of iterations to detect a hot loop or hot call + +hotexit + +10 + +Number of taken exits to start a side trace + +tryside + +4 + +Number of attempts to compile a side trace + +instunroll + +4 + +Max. unroll factor for instable loops + +loopunroll + +15 + +Max. unroll factor for loop ops in side traces + +callunroll + +3 + +Max. unroll factor for pseudo-recursive calls + +recunroll + +2 + +Min. unroll factor for true recursion + +sizemcode + +32 + +Size of each machine code area in KBytes (Windows: 64K) + +maxmcode + +512 + +Max. total size of all machine code areas in KBytes + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file running.html +# 13720 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/doc/LuaJIT-2.1/status.pod b/doc/LuaJIT-2.1/status.pod new file mode 100644 index 0000000..1ba0b1e --- /dev/null +++ b/doc/LuaJIT-2.1/status.pod @@ -0,0 +1,103 @@ +=pod + +LuaJIT + +=head1 Status + +=over + +=item * LuaJIT + +=over + +=item * Download E + +=item * Installation + +=item * Running + +=back + +=item * Extensions + +=over + +=item * FFI Library + +=over + +=item * FFI Tutorial + +=item * ffi.* API + +=item * FFI Semantics + +=back + +=item * jit.* Library + +=item * Lua/C API + +=item * Profiler + +=back + +=item * Status + +=over + +=item * Changes + +=back + +=item * FAQ + +=item * Performance E + +=item * Wiki E + +=item * Mailing List E + +=back + +LuaJIT 2.0 is the current stable branch. This branch is in +feature-freeze E new features will only be added to LuaJIT 2.1. + +=head2 Current Status + +LuaJIT ought to run all Lua 5.1-compatible source code just fine. It's +considered a serious bug if the VM crashes or produces unexpected +results E please report this. + +Known incompatibilities and issues in LuaJIT 2.0: + +=over + +=item * There are some differences in B +behavior. These either have a good reason, are arbitrary design choices +or are due to quirks in the VM. The latter cases may get fixed if a +demonstrable need is shown. + +=item * The Lua B is missing a couple of features (return +hooks for non-Lua functions) and shows slightly different behavior in +LuaJIT (no per-coroutine hooks, no tail call counting). + +=item * Currently some B errors from B +are not handled correctly. The error may fall through an on-trace +C or it may be passed on to the function set with C +on x64. This issue will be fixed with the new garbage collector. + +=back + +---- + +Copyright E 2005-2016 Mike Pall E Contact + +=cut + +#Pod::HTML2Pod conversion notes: +#From file status.html +# 3334 bytes of input +#Wed Jun 29 13:18:15 2016 agentzh +# No a_name switch not specified, so will not try to render +# No a_href switch not specified, so will not try to render diff --git a/util/mirror-tarballs b/util/mirror-tarballs index 32e63e5..dda64c6 100755 --- a/util/mirror-tarballs +++ b/util/mirror-tarballs @@ -494,7 +494,7 @@ mv openresty-redis2-nginx-module-* redis2-nginx-module-$ver || exit 1 ################################# -ver=0.12 +ver=0.13rc1 $root/util/get-tarball "https://github.com/openresty/resty-cli/tarball/v$ver" -O resty-cli-$ver.tar.gz || exit 1 tar -xzf resty-cli-$ver.tar.gz || exit 1 mv openresty-resty-cli-* resty-cli-$ver || exit 1 @@ -758,6 +758,9 @@ $restydoc_index --outdir bundle $root/work/nginx.org || exit 1 echo "restydoc-index $root/doc/lua-5.1.5" $restydoc_index --outdir bundle $root/doc/lua-5.1.5 || exit 1 +echo "restydoc-index $root/doc/LuaJIT-2.1" +$restydoc_index --outdir bundle $root/doc/LuaJIT-2.1 || exit 1 + # generate restydoc index from openresty docs for indir in bundle/*/; do

E Show full path for module names. + +=item * C E Show VM states. + +=item * C E Show zones. + +=item * C E Show raw sample counts. Default: show +percentages. + +=item * C E Annotate excerpts from source code files. + +=item * C E Annotate complete source code files. + +=item * C E Produce raw output suitable for graphical tools. + +=item * CnumberE> E Minimum sample percentage to be +shown. Default: 3%. + +=item * CnumberE> E Sampling interval in +milliseconds. Default: 10ms. + +Note: The actual sampling precision is OS-dependent. + +=back + +The default output for C<-jp> is a list of the most CPU consuming spots +in the application. Increasing the stack dump depth with (say) C<-jp=2> +may help to point out the main callers or callees of hotspots. But +sample aggregation is still flat per unique stack dump. + +To get a two-level view (split view) of callers/callees, use C<-jp=s> +or C<-jp=-s>. The percentages shown for the second level are relative +to the first level. + +To see how much time is spent in each line relative to a function, use +C<-jp=fl>. + +To see how much time is spent in different VM states or zones, use +C<-jp=v> or C<-jp=z>. + +Combinations of C with C produce two-level views, e.g. +C<-jp=vf> or C<-jp=fv>. This shows the time spent in a VM state or zone +vs. hotspots. This can be used to answer questions like "Which time +consuming functions are only interpreted?" or "What's the garbage +collector overhead for a specific function?". + +Multiple options can be combined E but not all combinations make +sense, see above. E.g. C<-jp=3si4m1> samples three stack levels deep in +4ms intervals and shows a split view of the CPU consuming functions and +their callers with a 1% threshold. + +Source code annotations produced by C<-jp=a> or C<-jp=A> are always +flat and at the line level. Obviously, the source code files need to be +readable by the profiler script. + +The high-level profiler can also be started and stopped from Lua code +with: + + require("jit.p").start(options, output) + ... + require("jit.p").stop() + +=head2 C E Zones + +Zones can be used to provide information about different parts of an +application to the high-level profiler. E.g. a game could make use of +an C<"AI"> zone, a C<"PHYS"> zone, etc. Zones are hierarchical, +organized as a stack. + +The C module needs to be loaded explicitly: + + local zone = require("jit.zone") + +=over + +=item * C pushes a named zone to the zone stack. + +=item * C pops the current zone from the zone stack and returns +its name. + +=item * C returns the current zone name or C. + +=item * C flushes the zone stack. + +=back + +To show the time spent in each zone use C<-jp=z>. To show the time +spent relative to hotspots use e.g. C<-jp=zf> or C<-jp=fz>. + +=head2 Low-level Lua API + +The C module gives access to the low-level API of the +profiler from Lua code. This module needs to be loaded explicitly: + + local profile = require("jit.profile") + +This module can be used to implement your own higher-level profiler. A +typical profiling run starts the profiler, captures stack dumps in the +profiler callback, adds them to a hash table to aggregate the number of +samples, stops the profiler and then analyzes all of the captured stack +dumps. Other parameters can be sampled in the profiler callback, too. +But it's important not to spend too much time in the callback, since +this may skew the statistics. + +=head2 C E Start profiler + +This function starts the profiler. The C argument is a string +holding options: + +=over + +=item * C E Profile with precision down to the function +level. + +=item * C E Profile with precision down to the line level. + +=item * CnumberE> E Sampling interval in milliseconds +(default 10ms). Note: The actual sampling precision is OS-dependent. + +=back + +The C argument is a callback function which is called with three +arguments: C<(thread, samples, vmstate)>. The callback is called on a +separate coroutine, the C argument is the state that holds the +stack to sample for profiling. Note: do I modify the stack of that +state or call functions on it. + +C gives the number of accumulated samples since the last +callback (usually 1). + +C holds the VM state at the time the profiling timer +triggered. This may or may not correspond to the state of the VM when +the profiling callback is called. The state is either C<'N'> native +(compiled) code, C<'I'> interpreted code, C<'C'> C code, C<'G'> the +garbage collector, or C<'J'> the JIT compiler. + +=head2 C E Stop profiler + +This function stops the profiler. + +=head2 C E Dump +stack + +This function allows taking stack dumps in an efficient manner. It +returns a string with a stack dump for the C (coroutine), +formatted according to the C argument: + +=over + +=item * C