-Coco is a small extension to get True C Coroutine
-semantics for Lua 5.1.
-
-
-Coco is both available as a stand-alone release and integrated
-into LuaJIT 1.x.
-
-
-The stand-alone release is a patchset against the
-» standard Lua 5.1.4
-distribution. There are no dependencies on LuaJIT. However LuaJIT 1.x
-depends on Coco to allow yielding for JIT compiled functions.
-
-True C coroutine semantics mean you can yield from a coroutine
-across a C call boundary and resume back to it.
-
-
-Coco allows you to use a dedicated C stack for each coroutine.
-Resuming a coroutine and yielding from a coroutine automatically switches
-C stacks, too.
-
-
-In particular you can now:
-
-
-
Yield across all metamethods (not advised for __gc).
-
Yield across iterator functions (for x in func do).
-
Yield across callbacks (table.foreach(), dofile(), ...).
-
Yield across protected callbacks (pcall(), xpcall(), ...).
-
Yield from C functions and resume back to them.
-
-
-Best of all, you don't need to change your Lua or C sources
-and still get the benefits. It's fully integrated into the
-Lua core, but tries to minimize the required changes.
-
-
-
More ...
-
-Please visit the » Download page
-to fetch the current version of the stand-alone package.
-
-
-Coco needs some machine-specific features — please have a look
-at the Portability Requirements.
-
-
-Coco also provides some upwards-compatible
-API Extensions for Lua.
-
-The optional argument cstacksize specifies the size of the
-C stack to allocate for the coroutine:
-
-
-
A default stack size is used if cstacksize is not given
-or is nil or zero.
-
No C stack is allocated if cstacksize is -1.
-
Any other value is rounded up to the minimum size
-(i.e. use 1 to get the minimum size).
-
-
-Important notice for LuaJIT: JIT compiled functions cannot
-yield if a coroutine does not have a dedicated C stack.
-
-
-
olddefault = coroutine.cstacksize([newdefault])
-
-Returns the current default C stack size (may be 0 if the
-underlying context switch method has its own default).
-Sets a new default C stack size if newdefault is present.
-Use 0 to reset it to the default C stack size. Any other
-value is rounded up to the minimum size.
-
-
-
C API extensions
-
-All C API functions are either unchanged or upwards compatible.
-
-
-
int lua_yield(lua_State *L, int nresults)
-
-The semantics for lua_yield() have changed slightly.
-Existing programs should work fine as long as they follow
-the usage conventions from the Lua manual:
-
-
-return lua_yield(L, nresults);
-
-
-Previously lua_yield() returned a 'magic' value (-1) that
-indicated a yield. Your C function had to pass this value
-on to the Lua core and was not called again.
-
-
-Now, if the current coroutine has an associated C stack,
-lua_yield() returns the number of arguments passed back from
-the resume. This just happens to be the right convention for
-returning them as a result from a C function. I.e. if you
-used the above convention, you'll never notice the change.
-
-
-But the results are on the Lua stack when lua_yield()
-returns. So the C function can just continue and process them
-or retry an I/O operation etc. And your whole C stack frame
-(local variables etc.) is still there, too. You can yield from
-anywhere in your C program, even several call levels deeper.
-
-
-Of course all of this only works with Lua+Coco and not with standard Lua.
-
-
-
lua_State *lua_newcthread(lua_State *L, int cstacksize)
-
-This is an (optional) new function that allows you to create
-a coroutine with an associated C stack directly from the C API.
-Other than that it works the same as lua_newthread(L).
-
-
-You have to declare this function as extern
-yourself, since it's not part of the official Lua API.
-This means that a C module that uses this call cannot
-be loaded with standard Lua. This may be intentional.
-
-
-If you want your C module to work with both standard Lua
-and Lua+Coco you can check whether Coco is available with:
-
Fix compilation of the GCC inline assembler code on x64.
-Now works when compiled as C++ code (reported by Jonathan Sauer)
-or with -fPIC (reported by Jim Pryor).
-
Added GCC inline assembler for faster context switching on Sparc.
-Thanks to Takayuki Usui.
-
-
-
Coco 1.1.5 — 2008-10-25
-
-
Upgraded to patch cleanly into Lua 5.1.4.
-
Added GCC inline assembler for faster context switching on x64.
-Thanks to Robert G. Jakabosky.
-
-
-
Coco 1.1.4 — 2008-02-05
-
-
Upgraded to patch cleanly into Lua 5.1.3.
-
Fixed setjmp method for ARM with recent glibc versions.
-Thanks to the LuaTeX developers.
-
Fixed setjmp method for x86 on Mac OS X (rarely used,
-default is GCC inline assembler). Thanks to Jason Toffaletti.
-
-
-
Coco 1.1.3 — 2007-05-24
-
-
Upgraded to patch cleanly into Lua 5.1.2.
-
Merged patch from Zachary P. Landau for a Linux/ARM setjmp method (uClibc and glibc).
-
-
-
Coco 1.1.1 — 2006-06-20
-
-
Upgraded to patch cleanly into Lua 5.1.1.
-
C stacks are deallocated early: when a coroutine ends, and not when
-the coroutine object is collected. This mainly benefits Windows Fibers.
-
Windows threads get the required Fiber context when resuming
-a coroutine and not just on creation.
-
-
-
Coco 1.1.0 — 2006-02-18
-
-
Upgraded to patch cleanly into Lua 5.1 (final).
-
Added GCC inline assembler for context switching on x86 and MIPS32
-[up to 3x faster].
-
New targets for setjmp method:
-Mac OS X/x86, Solaris/x86 and x64 and Linux/MIPS32.
-
Workaround for WinXP problem with GetCurrentFiber().
-
The minimum C stack size has been increased to 32K+4K.
-
Removed lcocolib.c and integrated the (much smaller) changes
-into lbaselib.c.
-Note for embedders: this means you no longer need to call
-luaopen_coco().
-
Optional Valgrind support requires version 3.x.
-Renamed define to USE_VALGRIND.
-
C stacks are now registered with Valgrind.
-
-
-
Coco pre-release 51w6 — 2005-08-09
-
-This is the first pre-release of Coco. It targets Lua 5.1-work6 only
-and is no longer available for download.
-
-Coco needs some machine-specific features which are
-inherently non-portable. Although the coverage is pretty good,
-this means that Coco will probably never be a standard part
-of the Lua core (which is pure ANSI C).
-
-
-
Context Switching Methods
-
-Coco relies on four different machine-specific methods
-for allocating a C stack and switching context.
-The appropriate method is automatically selected at compile time.
-
-
-
GCC Inline Assembler
-
-This method is only available when GCC 3.x/4.x is used
-to compile the source.
-This is the fastest method for context switching, but only available
-for a few CPUs (see below).
-
-
-
Modified setjmp Buffer
-
-This method changes a few fields in the setjmp buffer to
-redirect the next longjmp to a new function with a new stack
-frame. It needs a bit of guesswork and lots of #ifdef's to
-handle the supported CPU/OS combinations, but this is quite
-manageable.
-
-
-This is the fallback method if inline assembler is not available.
-It's pretty fast because it doesn't have to save or restore signals
-(which is slow and generally undesirable for Lua coroutines).
-
-
-
POSIX ucontext
-
-The POSIX calls getcontext, makecontext and switchcontext
-are used to set up and switch between different C stacks.
-Although highly portable and even available for some
-esoteric platforms, it's slower than the setjmp method
-because it saves and restores signals, too (using at least one
-syscall for each context switch).
-
-
-You can force the use of ucontext (instead of setjmp) by enabling
--DCOCO_USE_UCONTEXT in src/Makefile.
-
-
-
Windows Fibers
-
-This is the standard method to set up and switch between
-different C stacks on Windows. It's available on Windows 98
-and later.
-
-
-None of the other methods work for Windows because OS specific code
-is required to switch exception handling contexts.
-
-
-
Supported Platforms
-
-Coco has support for the following platforms:
-
-
-
-
CPU
-
System
-
Method
-
-
-
x86
(any OS)
gccasm
-
-
x86
Linux
setjmp
-
-
x86
FreeBSD
setjmp
-
-
x86
NetBSD
setjmp
-
-
x86
OpenBSD
setjmp
-
-
x86
Solaris
setjmp
-
-
x86
Mac OS X
setjmp
-
-
x64
(any OS)
gccasm
-
-
x64
Solaris
setjmp
-
-
MIPS32
(any OS)
gccasm
-
-
MIPS32
Linux
setjmp
-
-
ARM
Linux
setjmp
-
-
PPC32
Mac OS X
setjmp
-
-
(any CPU)
POSIX
ucontext
-
-
(any CPU)
Windows
fibers
-
-
-
-
-It should work pretty much anywhere where a correct
-POSIX ucontext implementation is available. It has been tested
-on every systems I could get hold of (e.g. Sparc, PPC32/PPC64,
-IA64, Alpha, HPPA with various operating systems).
-
-
-
Caveats
-
-
-Some older operating systems may have defective ucontext
-implementations because this feature is not widely used. E.g. some
-implementations don't mix well with other C library functions
-like malloc() or with native threads.
-This is really not the fault of Coco — please upgrade your OS.
-
-
-Note for Windows: Please read the explanation for the default
-» Thread Stack Size
-in case you want to create large numbers of Fiber-based coroutines.
-
-
-Note for MinGW/Cygwin: Older releases of GCC (before 4.0) generate
-wrong unwind information when -fomit-frame-pointer is used
-with stdcalls. This may lead to crashes when exceptions are thrown.
-The workaround is to always use two flags:
--fomit-frame-pointer -maccumulate-outgoing-args.
-
-
-Note for MIPS CPUs without FPU: It's recommended to compile
-all sources with -msoft-float, even if you don't use
-any floating point ops anywhere. Otherwise context switching must
-save and restore FPU registers (which needs to go through
-the slow kernel emulation).
-
-
-To run Coco with » Valgrind
-(a memory debugger) you must add -DUSE_VALGRIND
-to MYCFLAGS and recompile. You will get random errors
-if you don't! Valgrind 3.x or later is required. Earlier versions
-do not work well with newly allocated C stacks.
-
-DynASM is a Dynamic Assembler for code generation
-engines.
-
-
-DynASM has been developed primarily as a tool for
-LuaJIT, but might be useful for other
-projects, too.
-
-
-If you are writing a just-in-time compiler or need to generate
-code on the fly (e.g. for high-performance graphics or other
-CPU-intensive computations), DynASM might be just what you
-are looking for.
-
-
-Please have a look at the list of Features
-to find out whether DynASM could be useful for your project.
-
-Sorry, right now there is no proper documentation available other
-than some Examples and of course
-the source code. The source is well documented, though (IMHO).
-
-
-I may add more docs in case someone actually finds DynASM to be
-useful outside of LuaJIT. If you do, I'd like to
-hear from you, please. Thank you!
-
-
-If you want to check it out please visit the
-» Download page and fetch the most recent
-version of LuaJIT. All you need is in the dynasm directory.
-For some complex examples take a peek at the
-*.dasc and *.dash files in LuaJIT, too.
-
-Note: yes, you usually get the assembler code as comments and proper
-CPP directives to match them up with the source. I've omitted
-them here for clarity. Oh and BTW: the pipe symbols probably
-line up much more nicely in your editor than in a browser.
-
-
-Here 123 is an offset into the action list buffer that
-holds the partially specified machine code. Without going
-into too much detail, the embedded C library implements a
-tiny bytecode engine that takes the action list as input and
-outputs machine code. It basically copies machine code snippets
-from the action list and merges them with the arguments
-passed in by dasm_put().
-
-
-The arguments can be any kind of C expressions. In practical
-use most of them evaluate to constants (e.g. structure offsets).
-Your C compiler should generate very compact code out of it.
-
-
-The embedded C library knows only what's absolutely needed to
-generate proper machine code for the target CPU (e.g. variable
-displacement sizes, variable branch offset sizes and so on).
-It doesn't have a clue about other atrocities like x86 opcode
-encodings — and it doesn't need to. This dramatically
-reduces the minimum required code size to around 2K [sic!].
-
-
-The action list buffer itself has a pretty compact encoding, too.
-E.g. the whole action list buffer for an early version of LuaJIT
-needs only around 3K.
-
-
-
Advanced Features
-
-Here's a real-life example taken from LuaJIT that shows some
-advanced features like type maps, macros and how to access
-C structures:
-
The toolchain is split into a portable subset and
-CPU-specific modules.
-
DynASM itself (the pre-processor) is written in Lua.
-
There is no machine-dependency for the pre-processor itself.
-It should work everywhere you can get Lua 5.1 up and running
-(i.e. Linux, *BSD, Solaris, Windows, ... you name it).
-
-
-
DynASM Assembler Features
-
-
C code and assembler code can be freely mixed.
-Readable, too.
-
All the usual syntax for instructions and operand modes
-you come to expect from a standard assembler.
-
Access to C variables and CPP defines in assembler statements.
-
Access to C structures and unions via type mapping.
-
Convenient shortcuts for accessing C structures.
-
Local and global labels.
-
Numbered labels (e.g. for mapping bytecode instruction numbers).
-
Multiple code sections (e.g. for tailcode).
-
Defines/substitutions (inline and from command line).
-
Conditionals (translation time) with proper nesting.
-
Macros with parameters.
-
Macros can mix assembler statements and C code.
-
Captures (output diversion for code reordering).
-
Simple and extensible template system for instruction definitions.
-
-
-
Restrictions
-
-Currently only a subset of x86 (i386+) instructions is supported.
-Unsupported instructions are either not usable in user-mode or
-are slow on modern CPUs (i.e. not suited for a code generator).
-SSE, SSE2, SSE3 and SSSE3 are fully supported. MMX is not supported.
-
-
-The whole toolchain has been designed to support multiple CPU
-architectures. As LuaJIT gets support for more architectures,
-DynASM will be extended with new CPU-specific modules.
-
-
-The assembler itself will be extended with more features on an
-as-needed basis. E.g. I'm thinking about vararg macros.
-
-
-Note that runtime conditionals are not really needed, since you can
-just use plain C code for that (and LuaJIT does this a lot).
-It's not going to be more (time-) efficient if conditionals are done
-by the embedded C library (maybe a bit more space-efficient).
-
-DynASM —
-a Dynamic Assembler for code generation engines.
-
-
-
-
-
-
More ...
-
-Please click on one of the links in the navigation bar to your left
-to learn more.
-
-
-Click on the Logo in the upper left corner to visit
-the LuaJIT project page on the web. All other links to online
-resources are marked with a '»'.
-
-LuaJIT is a Just-In-Time Compiler for the Lua
-programming language.
-
-
-Lua is a powerful, light-weight programming language designed
-for extending applications. Lua is also frequently used as a
-general-purpose, stand-alone language. More information about
-Lua can be found at: » http://www.lua.org/
-
-
-LuaJIT 1.x is based on the Lua 5.1.x virtual machine and bytecode interpreter
-from lua.org. It compiles bytecode to native x86 (i386+) machine code
-to speed up the execution of Lua programs.
-
-
-LuaJIT depends on Coco to allow yielding
-from coroutines for JIT compiled functions. Coco is part of the
-LuaJIT distribution.
-
-All standard library functions have the same behaviour as
-in the Lua distribution LuaJIT is based on.
-
-
-The Lua loader used by the standard require() library
-function has been modified to turn off compilation of the main
-chunk of a module. The main chunk is only run once when the module
-is loaded for the first time. There is no point in compiling it.
-
-
-You might want to adapt this behaviour if you use your own utility
-functions (and not require()) to load modules.
-
-
-Note that the subfunctions defined in a loaded module are
-of course compiled. See below if you want to override this.
-
-
-
The jit.* Library
-
-This library holds several functions to control the behaviour
-of the JIT engine.
-
-
-
jit.on()
-jit.off()
-
-Turns the JIT engine on (default) or off.
-
-
-These functions are typically used with the command line options
--j on or -j off.
-
-Enable (with jit.on, default) or disable (with jit.off)
-JIT compilation for a Lua function. The current function (the Lua function
-calling this library function) can be specified with true.
-
-
-If the second argument is true, JIT compilation is also
-enabled/disabled recursively for all subfunctions of a function.
-With false only the subfunctions are affected.
-
-
-Both library functions only set a flag which is checked when
-the function is executed for the first/next time. They do not
-trigger immediate compilation.
-
-
-Typical usage is jit.off(true, true) in the main chunk
-of a module to turn off JIT compilation for the whole module.
-Note that require() already turns off compilation for
-the main chunk itself.
-
-
-
status = jit.compile(func [,args...])
-
-Compiles a Lua function and returns the compilation status.
-Successful compilation is indicated with a nil status.
-Failure is indicated with a numeric status (see jit.util.status).
-
-
-The optimizer pass of the compiler tries to derive hints from the
-passed arguments. Not passing any arguments or passing untypical
-arguments (esp. the wrong types) reduces the efficiency of the
-optimizer. The compiled function will still run, but probably not
-with maximum speed.
-
-
-This library function is typically used for Ahead-Of-Time (AOT)
-compilation of time-critical functions or for testing/debugging.
-
-
-
status = jit.compilesub(func|true [,true])
-
-Recursively compile all subfunctions of a Lua function.
-The current function (the Lua function calling this library function)
-can be specified with true. Note that the function
-itself is not compiled (use jit.compile()).
-
-
-If the second argument is true, compilation will stop
-when the first error is encountered. Otherwise compilation will
-continue with the next subfunction.
-
-
-The returned status is nil, if all subfunctions have been
-compiled successfully. A numeric status (see jit.util.status)
-indicates that at least one compilation failed and gives the status
-of the last failure (this is only helpful when stop on error
-is true).
-
-
-
jit.debug([level])
-
-Set the debug level for JIT compilation. If no level is given,
-the maximum debug level is set.
-
-
-
Level 0 disables debugging: no checks for hooks are compiled
-into the code. This is the default when LuaJIT is started and
-provides the maximum performance.
-
Level 1 enables function call debugging: call hooks and
-return hooks are checked in the function prologue and epilogue.
-This slows down function calls somewhat (by up to 10%).
-
Level 2 enables full debugging: all hooks are checked.
-This slows down execution quite a bit, even when the hooks
-are not active.
-
-
-Note that some compiler optimizations are turned off when
-debugging is enabled.
-
-
-This function is typically used with the command line options
--j debug or -j debug=level.
-
-
-
jit.attach(handler [, priority])
-
-Attach a handler to the compiler pipeline with the given priority.
-The handler is detached if no priority is given.
-
-
-The inner workings of the compiler pipeline and the API for handlers
-are still in flux. Please see the source code for more details.
-
-
-
jit.version
-
-Contains the LuaJIT version string.
-
-
-
jit.version_num
-
-Contains the version number of the LuaJIT core. Version xx.yy.zz
-is represented by the decimal number xxyyzz.
-
-
-
jit.arch
-
-Contains the target architecture name (CPU and optional ABI).
-
-
-
-
The jit.util.* Library
-
-This library holds many utility functions used by the provided
-extension modules for LuaJIT (e.g. the optimizer). The API may
-change in future versions.
-
-
-
stats = jit.util.stats(func)
-
-Retrieves information about a function. Returns nil
-for C functions. Returns a table with the following fields for
-Lua functions:
-
-
-
status: numeric compilation status (see jit.util.status).
-
stackslots: number of stack slots.
-
params: number of fixed parameters (arguments).
-
consts: number of constants.
-
upvalues: number of upvalues.
-
subs: number of subfunctions (sub prototypes).
-
bytecodes: number of bytecode instructions.
-
isvararg: fixarg (false) or vararg (true) function.
-
env: function environment table.
-
mcodesize: size of the compiled machine code.
-
mcodeaddr: start address of the compiled machine code.
-
-
-mcodesize and mcodeaddr are not set if the
-function has not been compiled (yet).
-
-
-
op, a, b, c, test = jit.util.bytecode(func, pc)
-
-Returns the fields of the bytecode instruction at the given pc
-for a Lua function. The first instruction is at pc = 1.
-Nothing is returned if pc is out of range.
-
-
-The opcode name is returned as an uppercase string in op.
-The opcode arguments are returned as a, b and
-optionally c. Arguments that indicate an index into the
-array of constants are translated to negative numbers (the first
-constant is referred to with -1). Branch targets are signed numbers
-relative to the next instruction.
-
-
-test is true if the instruction is a test (i.e. followed
-by a JMP).
-
-
-
const, ok = jit.util.const(func, idx)
-
-Returns a constant from the array of constants for a Lua function.
-ok is true if idx is in range. Otherwise nothing
-is returned.
-
-
-Constants are numbered starting with 1. A negative idx
-is mapped to a positive index.
-
-
-
upvalue, ok = jit.util.upvalue(func, idx)
-
-Returns an upvalue from the array of upvalues for a Lua function.
-ok is true if idx is in range. Otherwise nothing
-is returned. Upvalues are numbered starting with 0.
-
-
-
nup = jit.util.closurenup(func, idx)
-
-Returns the number of upvalues for the subfunction prototype with
-the given index idx for a Lua function. Nothing is returned
-if idx is out of range. Subfunctions are numbered starting
-with 0.
-
-Returns the numeric start address, the compiled machine code
-(converted to a string) and an iterator for the machine code fragment map
-for the specified machine code block associated with a Lua function.
-
-
-Returns nil and a numeric status code (see jit.util.status)
-if the function has not been compiled yet or compilation has failed
-or compilation is disabled. Returns nothing if the selected
-machine code block does not exist.
-
-
-The machine code fragment map is used for debugging and error handling.
-The format may change between versions and is an internal implementation
-detail of LuaJIT.
-
-
-
addr [, mcode] = jit.util.jsubmcode([idx])
-
-If idx is omitted or nil:
-Returns the numeric start address and the compiled machine code
-(converted to a string) for internal subroutines used by the
-compiled machine code.
-
-
-If idx is given:
-Returns the numeric start address of the machine code for a specific
-internal subroutine (0 based). Nothing is returned if idx is
-out of range.
-
-
-
jit.util.status
-
-This is a table that bidirectionally maps status numbers and
-status names (strings):
-
-
-
-
Status Name
Description
-
OK
Ok, code has been compiled.
-
NONE
Nothing analyzed or compiled, yet (default).
-
OFF
Compilation disabled for this function.
-
ENGINE_OFF
JIT engine is turned off.
-
DELAYED
Compilation delayed (recursive invocation).
-
TOOLARGE
Bytecode or machine code is too large.
-
COMPILER_ERROR
Error from compiler frontend.
-
DASM_ERROR
Error from DynASM engine.
-
-
-
-
jit.util.hints
-jit.util.fhints
-
-These two tables map compiler hint names to internal hint numbers.
-
-
-The hint system is an internal implementation detail of LuaJIT.
-Please see the source code for more info.
-
Remove a (sometimes) wrong assertion in luaJIT_findpc().
-
DynASM now allows labels for displacements and .aword.
-
Fix some compiler warnings for DynASM glue (internal API change).
-
Correct naming for SSSE3 (temporarily known as SSE4) in DynASM and x86 disassembler.
-
The loadable debug modules now handle redirection to stdout
-(e.g. -j trace=-).
-
-
-
LuaJIT 1.1.2 — 2006-06-24
-
-
Fix MSVC inline assembly: use only local variables with
-lua_number2int().
-
Fix "attempt to call a thread value" bug on Mac OS X:
-make values of consts used as lightuserdata keys unique
-to avoid joining by the compiler/linker.
The C stack is kept 16 byte aligned (faster).
-Mandatory for Mac OS X on Intel, too.
-
Faster calling conventions for internal C helper functions.
-
Better instruction scheduling for function prologue, OP_CALL and
-OP_RETURN.
-
-
-
Miscellaneous optimizations:
-
-
Faster loads of FP constants. Remove narrow-to-wide store-to-load
-forwarding stalls.
-
Use (scalar) SSE2 ops (if the CPU supports it) to speed up slot moves
-and FP to integer conversions.
-
Optimized the two-argument form of OP_CONCAT (a..b).
-
Inlined OP_MOD (a%b).
-With better accuracy than the C variant, too.
-
Inlined OP_POW (a^b). Unroll x^k or
-use k^x = 2^(log2(k)*x) or call pow().
-
-
-
Changes in the optimizer:
-
-
Improved hinting for table keys derived from table values
-(t1[t2[x]]).
-
Lookup hinting now works with arbitrary object types and
-supports index chains, too.
-
Generate type hints for arithmetic and comparison operators,
-OP_LEN, OP_CONCAT and OP_FORPREP.
-
Remove several hint definitions in favour of a generic COMBINE hint.
-
Complete rewrite of jit.opt_inline module
-(ex jit.opt_lib).
-
-
-
Use adaptive deoptimization:
-
-
If runtime verification of a contract fails, the affected
-instruction is recompiled and patched on-the-fly.
-Regular programs will trigger deoptimization only occasionally.
-
This avoids generating code for uncommon fallback cases
-most of the time. Generated code is up to 30% smaller compared to
-LuaJIT 1.0.3.
-
Deoptimization is used for many opcodes and contracts:
-
-
OP_CALL, OP_TAILCALL: type mismatch for callable.
-
Inlined calls: closure mismatch, parameter number and type mismatches.
-
OP_GETTABLE, OP_SETTABLE: table or key type and range mismatches.
-
All arithmetic and comparison operators, OP_LEN, OP_CONCAT,
-OP_FORPREP: operand type and range mismatches.
-
-
Complete redesign of the debug and traceback info
-(bytecode ↔ mcode) to support deoptimization.
-Much more flexible and needs only 50% of the space.
-
The modules jit.trace, jit.dumphints and
-jit.dump handle deoptimization.
-
-
-
Inlined many popular library functions
-(for commonly used arguments only):
-
-
Most math.* functions (the 18 most used ones)
-[2x-10x faster].
-
string.len, string.sub and string.char
-[2x-10x faster].
-
table.insert, table.remove and table.getn
-[3x-5x faster].
-
coroutine.yield and coroutine.resume
-[3x-5x faster].
-
pairs, ipairs and the corresponding iterators
-[8x-15x faster].
-
-
-
Changes in the core and loadable modules and the stand-alone executable:
-
-
Added jit.version, jit.version_num
-and jit.arch.
-
Reorganized some internal API functions (jit.util.*mcode*).
-
The -j dump output now shows JSUB names, too.
-
New x86 disassembler module written in pure Lua. No dependency
-on ndisasm anymore. Flexible API, very compact (500 lines)
-and complete (x87, MMX, SSE, SSE2, SSE3, SSSE3, privileged instructions).
-
luajit -v prints the LuaJIT version and copyright
-on a separate line.
-
-
-
Added SSE, SSE2, SSE3 and SSSE3 support to DynASM.
-
Miscellaneous doc changes. Added a section about
-embedding LuaJIT.
-LuaJIT is a rather complex application. There will undoubtedly
-be bugs lurking in there. You have been warned. :-)
-
-
-If you came here looking for information on how to debug
-your application (and not LuaJIT itself) then please
-check out jit.debug()
-and the -j debug
-command line option.
-
-
-But if you suspect a problem with LuaJIT itself, then try
-any of the following suggestions (in order).
-
-
-
Is LuaJIT the Problem?
-
-Try to run your application in several different ways:
-
-
-
luajit app.lua
-
luajit -O1 app.lua
-
luajit -O app.lua
-
luajit -j off app.lua
-
lua app.lua (i.e. with standard Lua)
-
-
-If the behaviour is the same as with standard Lua then ...
-well ... that's what LuaJIT is about: doing the same things,
-just faster. Even bugs fly faster. :-)
-
-
-So this is most likely a bug in your application then. It may be easier
-to debug this with plain Lua — the remainder of this page
-is probably not helpful for you.
-
-
-But if the behaviour is different, there is some likelihood
-that you caught a bug in LuaJIT. Oh dear ...
-
-
-Ok, so don't just give up. Please read on and help the community
-by finding the bug. Thank you!
-
-Please check if a newer version is available. Maybe the bug
-you have encountered has been fixed already. Always download the
-latest version and try it with your application before continuing.
-
-
-
Reproduce the Bug
-
-First try to make the bug reproducible. Try to isolate the module
-and the function the bug occurs in:
-
-
-Either selectively turn off compilation for some modules with
- jit.off(true, true)
-until the bug disappears ...
-
-
-And/or turn the whole JIT engine off and selectively compile
-functions with
- jit.compile(func)
-until it reappears.
-
-
-If you have isolated the point where it happens, it's most helpful
-to reduce the affected Lua code to a short code snippet that
-still shows the problem. You may need to print() some
-variables until you can pinpoint the exact spot where it happens.
-
-
-If you've got a reproducible and short test
-you can either send it directly to me or the mailing list
-(see the Contact Information)
-or you can try to debug this a bit further.
-
-
-Well — if you are brave enough. :-)
-
-
-
Look at the Generated Code
-
-You may want to have a look at the output of -j dumphints
-first. Try to change things around until you can see which hint
-or which instruction is the cause of the bug. If you suspect
-an optimizer bug then have a look at the backend (*.das[ch])
-and check how the hint is encoded.
-
-
-Otherwise have a look at -j dump and see whether
-you can spot the problem around the affected instruction.
-It's helpful to have a good knowledge of assembler, though
-(sorry).
-
-
-
Locate a Crash
-
-If you get a crash, you should compile LuaJIT with debugging
-turned on:
-
-
-Add -g to CFLAGS and MYLDFLAGS
-or whatever is needed to turn on debugging. For Windows you
-need both an executable and a DLL built with debugging.
-
-
-Then start LuaJIT with your debugger. Run it with
--j dump=test.dump.
-
-
-Have a look at the backtrace and compare it with the generated
-dump file to find out exactly where it crashes. I'm sorry, but
-symbols or instructions for JIT compiled functions are not
-displayed in your debugger (this is really hard to solve).
-
-
-
Turn on Assertions
-
-Another way to debug LuaJIT is to turn on assertions.
-They can be turned on only for the JIT engine by adding
--DLUAJIT_ASSERT to JITCFLAGS in src/Makefile.
-Then recompile with make clean and make.
-
-
-Add these two lines to src/luaconf.h to turn on all assertions in the Lua core:
- #include <assert.h>
- #define lua_assert(x) assert(x)
-This turns on the JIT engine assertions, too.
-Recompile and see whether any assertions trigger.
-Don't forget to turn off the (slow) assertions when you're done!
-
-
-
Use Valgrind
-
-A tremendously useful (and free) tool for runtime code analysis
-is » Valgrind. Regularly
-run your applications with valgrind --memcheck and
-your life will be better.
-
-
-To run LuaJIT under Valgrind you must add
--DUSE_VALGRIND to MYCFLAGS
-and recompile LuaJIT. You will get random errors if you don't!
-Valgrind 3.x or later is required. Earlier versions
-do not work well with newly allocated C stacks.
-
-
-An executable built with this option runs fine without Valgrind
-and without a performance loss. But it needs the Valgrind header
-files for compilation (which is why it's not enabled by default).
-
-
-It's helpful to compile LuaJIT with debugging turned on, too
-(see above).
-
-
-If Valgrind spots many invalid memory accesses that involve
-memory allocation/free functions you've probably found a bug
-related to garbage collection. Some object reference must have
-gone astray.
-
-
-Try to find out which object is disappearing. You can force
-eager garbage collection with repeated calls to
-collectgarbage() or by setting a very low threshold
-with collectgarbage("setpause", 1).
-
-
-
Don't Despair
-
-If all of this doesn't help to find the bug, please send
-a summary of your findings to the mailing list. Describe as much
-of the circumstances you think are relevant.
-
-
-Please don't send your whole application to me
-(without asking first) and especially not to the mailing list.
-Code snippets should preferrably be less than 50 lines and
-up to the point.
-
-
-All bug reports are helpful, even if no immediate solution
-is available. Often enough someone else finds the same bug
-in a different setting and together with your bug report
-this may help to track it down.
-
-
-Finally I have to say a BIG THANK YOU
-to everyone who has helped to make LuaJIT better by finding
-and fixing bugs!
-
Adaptive deoptimization is used to recompile individual bytecode
-instructions with broken contracts. This avoids generating code for the
-generic fallback cases most of the time (faster compilation, reduced
-I-cache contention).
-
Special CPU features (such as conditional moves or SSE2)
-are automatically used when detected.
-
-
-The JIT compiler is very fast:
-
-
-
Compilation times vary a great deal (depending on the nature of
-the function to be compiled) but are generally in the
-microsecond range.
-
Even compiling large functions (hundreds of lines) with the
-maximum optimization level takes only a few milliseconds in the
-worst case.
-
-
-LuaJIT is very small:
-
-
-
The whole JIT compiler engine adds only around 32K
-of code to the Lua core (if compiled with -Os).
-
The optimizer is split into several optional modules that
-can be loaded at runtime if requested.
-
LuaJIT adds around 6.000 lines of C and assembler code and
-2.000 lines of Lua code to the Lua 5.1 core (17.000 lines of C).
-
Required build tools (DynASM)
-take another 2.500 lines of Lua code.
-
-
-
Compatibility
-
-LuaJIT is designed to be fully compatible with Lua 5.1.
-It accepts the same source code and/or precompiled bytecode.
-It supports all standard language semantics. In particular:
-
-
-
All standard types, operators and metamethods are supported.
-
Implicit type coercions (number/string) work as expected.
-
Full IEEE-754 semantics for floating point arithmetics
-(NaN, +-Inf, +-0, ...).
-
Full support for lexical closures.
-Proper tail calls do not consume a call frame.
No changes to the Lua 5.1 incremental garbage collector.
-
No changes to the standard Lua/C API.
-
Dynamically loaded C modules are link compatible with Lua 5.1
-(same ABI).
-
LuaJIT can be embedded
-into an application just like Lua.
-
-
-Some minor differences are related to debugging:
-
-
-
Debug hooks are only called if debug code generation is enabled.
-
There is no support for tailcall counting in JIT compiled code.
-HOOKTAILRET is not called, too. Note: this won't affect you unless
-you are writing a Lua debugger. *
-
-
-* There is not much I can do to improve this situation without undue
-complications. A suggestion to modify the behaviour of standard Lua
-has been made on the mailing list (it would be beneficial there, too).
-
-
-
Restrictions
-
-
Only x86 (i386+) CPUs are supported right now (but see below).
-
Only the default type for lua_Number is supported
-(double).
-
The interrupt signal (Ctrl-C) is ignored unless you enable
-debug hooks (with -j debug). But this will seriously
-slow down your application. I'm looking for better ways to handle
-this. In the meantime you have to press Ctrl-C twice to interrupt
-a currently running JIT compiled function (just like C functions).
-
GDB, Valgrind and other debugging tools can't report symbols
-or stack frames for JIT compiled code. This is rather difficult to solve.
-Have a look at Debugging LuaJIT, too.
-
-
-
Caveats
-
-
LuaJIT allocates executable memory for the generated machine code
-if your OS has support for it: either HeapCreate() for Windows or
-mmap() on POSIX systems.
-The fallback is the standard Lua allocator (i.e. malloc()).
-But this usually means the allocated memory is not marked executable.
-Running compiled code will trap on CPUs/OS with the NX (No eXecute)
-extension if you can only use the fallback.
-
DynASM is needed to regenerate the
-ljit_x86.h file. But only in case you want to modify
-the *.dasc/*.dash files. A pre-processed *.h
-file is supplied with LuaJIT.
-DynASM is written in Lua and needs a plain copy of Lua 5.1
-(installed as lua). Or you can run it with LuaJIT built from
-the *.h file supplied with the distribution (modify
-DASM= in src/Makefile). It's a good idea to install
-a known good copy of LuaJIT under a different name for this.
-
LuaJIT ships with LUA_COMPAT_VARARG turned off.
-I.e. the implicit arg parameter is not created anymore.
-Please have a look at the comments in luaconf.h for
-this configuration option. You can turn it on, if you really need it.
-Or better yet, convert your code to the new Lua 5.1 vararg syntax.
-LuaJIT is not much more difficult to install than Lua itself.
-Just unpack the distribution file, change into the newly created
-directory and follow the instructions below.
-
-
-For the impatient: make linux && sudo make install
-Replace linux with e.g. bsd or macosx depending on your OS.
-
-
-In case you've missed this in Features:
-LuaJIT only works on x86 (i386+) systems right now. Support for
-other architectures may be added in future versions.
-
-
-
Configuring LuaJIT
-
-LuaJIT is (deliberately) not autoconfigured — the
-defaults should work fine on most systems. But please check the
-system-specific instructions below.
-
-
-The following three files hold all configuration information:
-
-
-
Makefile holds settings for installing LuaJIT.
-
src/Makefile holds settings for compiling LuaJIT.
-
src/luaconf.h sets a multitude of configuration
-variables.
-
-
-If this is your first build then it's better not to give into
-the temptation to tweak every little setting. The standard
-configuration provides sensible defaults (IMHO).
-
-
-One particular setting you might want to change is the installation
-path. Note that you need to modify both the top-level Makefile
-and src/luaconf.h (right at the start) to take
-effect.
-
-
-If you have trouble getting Coco to work, you can disable it by
-uncommenting the COCOFLAGS= -DCOCO_DISABLE line in
-src/Makefile. But note that this effectively disables
-yielding from coroutines for JIT compiled functions.
-
-
-A few more settings need to be changed if you want to
-Debug LuaJITitself.
-Application debugging can be turned on/off at runtime.
-
-
-
Upgrading From Previous Versions
-
-It's important to keep the LuaJIT core and the add-on modules in sync.
-Be sure to delete any old versions of LuaJIT modules from the
-Lua module search path (check the current directory, too!).
-
-
-Lua files compiled to bytecode may be incompatible if the underlying
-Lua core has changed (like from Lua 5.1 alpha to Lua 5.1
-final between LuaJIT 1.0.3 and LuaJIT 1.1.0). The same
-applies to any
-» loadable C modules
-(shared libraries, DLLs) which need to be recompiled with the new
-Lua header files.
-
-
-Compiled bytecode and loadable C modules are fully compatible and
-can be freely exchanged between LuaJIT and the same
-version of Lua it is based on. Please verify that LUA_RELEASE
-in src/lua.h is the same in both distributions.
-
-
-
Building LuaJIT
-
-
Makefile Targets
-
-The Makefiles have a number of targets for various operating systems:
-
-You may want to enable interactive line editing for the stand-alone
-executable. There are extra targets for Linux, BSD and Mac OS X:
-make linux_rl, make bsd_rl
-and make macosx_rl.
-
-
-
MSVC (Win32)
-
-First check out etc\luavs.bat if it suits your needs. Then try
-running it from the MSVC command prompt (start it from the toplevel directory).
-
-
-Another option is to set up your own MSVC project:
-
-
-Change to the src directory
-and create a new DLL project for lua51.dll.
-Add all C files to it except for lua.c, luac.c
-and print.c. Add the ..\dynasm directory
-to the include path and build the DLL.
-
-
-Next create a new EXE project for luajit.exe.
-Add lua.c to it and link with the import library
-lua51.lib created for lua51.dll. Build
-the executable.
-
-
-
Installation
-
-
POSIX systems
-
-Run make install from the top-level directory.
-You probably need to be the root user before doing so, i.e. use
-sudo make install or su - root
-before the make install.
-
-
-By default this installs only:
- /usr/local/bin/luajit — The stand-alone executable.
- /usr/local/lib/lua/5.1 — C module directory.
- /usr/local/share/lua/5.1 — Lua module directory.
- /usr/local/share/lua/5.1/jit/*.lua —
-jit.* modules.
-
-
-The Lua docs and includes are not installed to avoid overwriting
-an existing Lua installation. In any case these are identical
-to the version of Lua that LuaJIT is based on. If you want
-to install them, edit the top-level makefile (look for ###).
-
-
-The stand-alone Lua bytecode compiler luac is neither
-built nor installed, for the same reason. If you really need it,
-you may be better off with luac built from the original Lua
-distribution (use the same version your copy of LuaJIT
-is based on). This avoids dragging in most of LuaJIT which is not
-needed for the pure bytecode compiler. You can also use the bare-bones
-Lua to bytecode translator luac.lua (look in the test
-directory of the original Lua distribution).
-
-
-
Windows
-
-Copy luajit.exe and lua51.dll
-to a newly created directory (any location is ok). Add lua
-and lua\jit directories below it and copy all Lua files
-from the jit directory of the distribution to the latter directory.
-
-
-There are no hardcoded
-absolute path names — all modules are loaded relative to the
-directory where luajit.exe is installed
-(see src/luaconf.h).
-
-
-
Embedding LuaJIT
-
-It's strongly recommended that you build the stand-alone executable
-with your toolchain and verify that it works before starting
-to embed LuaJIT into an application. The stand-alone executable is
-also useful later on, when you want to experiment with code snippets
-or try out some Lua files.
-
-
-Please consult the Lua docs for general information about how to
-embed Lua into your application. The following list only shows
-the additional steps needed for embedding LuaJIT:
-
-
-
You need to add the LuaJIT library functions by running
-luaopen_jit() after all the other standard library functions.
-The modified src/linit.c used by the stand-alone executable
-already does this for you.
-
Caveat: LuaJIT is based on Lua 5.1 which
-means the luaopen_*() functions must not
-be called directly. See src/linit.c for the proper way to
-run them. You'll get an error initializing the io library
-if you don't follow these instructions.
-
To use the optimizer (strongly recommended) you need to:
-
-
Install the optimizer modules jit.opt and
-jit.opt_inline relative to the Lua module path
-(you've probably modified it — see src/luaconf.h):
-jit/opt.lua
-jit/opt_inline.lua
-
If you want to ship a single executable then you may want to
-embed the optimizer modules into your application (but don't loose
-time with this during the early development phase). This involves:
-
-
Compile the two modules to bytecode
-(using luac -s from a plain Lua installation).
-
Convert them to C include files (search for "Lua bin2c").
-
On Windows you can also put the compiled bytecode into a resource
-(search for "Lua bin2res").
-
Load the bytecode with luaL_loadbuffer (but don't run it).
-
Put the resulting functions into package.preload["jit.opt"]
-and package.preload["jit.opt_inline"].
-
-
Activate the LuaJIT optimizer from Lua code to be run at startup:
- require("jit.opt").start()
-Or use equivalent C code. See dojitopt() in src/lua.c.
-
-
All other LuaJIT specific modules (jit.*) are for debugging only.
-They do not need to be shipped with an application. But they may be quite
-useful, anyway (especially jit.trace).
-
DynASM is only needed while building LuaJIT. It's not
-needed while running LuaJIT and there is no point in shipping or
-installing it together with an application.
-
In case you want to strip some of the standard libraries from
-your application: The optimizer modules need several functions from
-the base library and the string library (and of course the LuaJIT
-core libraries). The io library is only used to print a fatal error
-message (you may want to replace it). The optional modules
-for debugging depend on a few more library functions —
-please check the source.
-
-
-Although the very liberal LuaJIT
-» license
-does not require any acknowledgment whatsoever, it would be appreciated
-if you give some credit in the docs (or the "About" box) of your application.
-A simple line like:
- This product includes LuaJIT, http://luajit.org/
-would be nice. Please do not include any E-Mail addresses. Thank you!
-
-
-I'm always interested where LuaJIT can be put to good use in applications.
-Please tell me
-or better yet write a few lines about your project to the
-» Lua mailing list.
-Thank you!
-
-This is a little essay that tries to answer the question:
-'So, how does LuaJIT really work?'.
-
-
-I tried to avoid going into all the gory details, but at the
-same time provide a deep enough explanation, to let you find
-your way around LuaJIT's inner workings.
-
-
-The learning curve is maybe a little bit steep for newbies and
-compiler gurus will certainly fall asleep after two paragraphs.
-It's difficult to strike a balance here.
-
-
-
Acronym Soup
-
-As the name says LuaJIT is a Just-In-Time (JIT) compiler.
-This means that functions are compiled on demand, i.e. when they
-are run first. This ensures both a quick application startup
-and helps to avoid useless work, too. E.g. unused functions
-are not compiled at all.
-
-
-The other alternative is known as Ahead-Of-Time (AOT)
-compilation. Here everything is compiled before running any function.
-This is the classic way for many languages, such as C or C++.
-
-
-In fact plain Lua allows you to pre-compile Lua source code into
-Lua bytecode and store it in a binary file that can be run
-later on. This is used only in specific settings (e.g. memory limited
-embedded systems), because the Lua bytecode compiler is really fast.
-The ability to run source files right away is part of what makes
-a dynamic language (aka scripting language) so powerful.
-
-
-JIT compilation has a few other advantages for dynamic languages
-that AOT compilation can only provide with a massive amount
-of code analysis. More can be found in the literature.
-One particular advantage is explained later.
-
-
-
Quick, JIT — Run!
-
-JIT compilation happens mostly invisible. You'll probably never
-notice that a compilation is going on. Part of the secret is
-that everything happens in little pieces intermixed with running
-the application itself inbetween. The other part of the secret
-is that JIT compilation can be made pretty fast.
-
-
-Most applications quickly converge to a stable state where
-everything that really needs to be compiled is compiled
-right away. Only occasional isolated compiles happen later on.
-
-
-Even though the name doesn't suggest it, LuaJIT can operate
-in AOT mode, too. But this is completely under user control
-(see jit.compile())
-and doesn't happen automatically.
-
-
-Unless you have good reason to suspect that AOT compilation
-might help for a specific application, I wouldn't bother though.
-Compilation speed is usually a non-argument, because LuaJIT
-is extremely fast. Compilation times are typically in the
-microsecond range for individual Lua functions.
-
-
-
Starting Up
-
-The next few paragraphs may not be exactly breaking news to you,
-if you are familiar with JIT compilers. Still, please read on,
-because some terms are introduced that are used later on.
-
-
-When you start LuaJIT everything proceeds like in standard Lua:
-the Lua core is initialized, the standard libraries are loaded and
-the command line is analyzed. Then usually the first Lua source
-code file is loaded and is translated to Lua bytecode. And finally
-the function for the initial main chunk is run ...
-
-
-
Kicking the Compiler
-
-This is where LuaJIT kicks in:
-
-
-All Lua functions carry an additional status code for LuaJIT.
-Initially this is set to 'NONE', i.e. the function has not been
-looked at (yet). If a function is run with this setting,
-the LuaJIT compiler pipeline is started up.
-
-
-If you haven't loaded any special LuaJIT modules and optimization
-is not turned on, the compiler pipeline only consists of the
-compiler backend.
-
-
-The compiler backend is the low-level encoding engine that translates
-bytecode instructions to machine code instructions. Without any
-further hints from other modules, the backend more or less does a
-1:1 translation. I.e. a single variant of a bytecode instruction
-corresponds to a single piece of machine code.
-
-
-If all goes well, these little code pieces are put together,
-a function prologue is slapped on and voila: your Lua function
-has been translated to machine code. Of course things are not
-that simple when you look closer, but hey — this is
-the theory.
-
-
-Anyway, the status code for the function is set to 'OK' and the
-machine code is run. If this function runs another Lua function
-which has not been compiled, that one is compiled, too. And so on.
-
-
-
Call Gates
-
-Ok, so what happens when a function is called repeatedly? After all
-this is the most common case.
-
-
-Simple: The status code is checked again. This time it's set to 'OK',
-so the machine code can be run directly. Well — that's not the
-whole truth: for calls that originate in a JIT compiled function
-a better mechanism, tentatively named call gates is used.
-
-
-Every function has a call gate field (a function pointer). By default
-it's set to a function that does the above checks and runs the
-compiler. But as soon as a function is compiled, the call gate
-is modified to point to the just compiled machine code.
-
-
-Calling a function is then as easy as calling the code that the
-call gate points to. But due to special (faster) calling conventions
-this function pointer cannot be used directly from C. So calls from
-a non-compiled function or from a C function use an extra entry
-call gate which in turn calls the real call gate. But this is
-really a non-issue since most calls in typical applications
-are intra-JIT calls.
-
-
-
The Compiler Pipeline
-
-The compiler pipeline has already been mentioned. This sounds
-more complicated than it is. Basically this is a coroutine that
-runs a frontend function which in turn calls all functions
-from the pipeline table.
-
-
-The pipeline table is sorted by priorities. The standard
-backend has priority 0. Positive priorities are run before the
-backend and negative priorities are run after the backend. Modules
-can dynamically attach or detach themselves to the pipeline with
-the library function jit.attach().
-
-
-So a typical optimizer pass better have a positive priority,
-because it needs to be run before the backend is run. E.g. the
-LuaJIT optimizer module registers itself with priority 50.
-
-
-On the other hand a typical helper module for debugging —
-a machine code disassembler — needs to be run after the
-backend and is attached with a negative priority.
-
-
-One special case occurs when compilation fails. This can be due to
-an internal error (ouch) or on purpose. E.g. the optimizer module
-checks some characteristics of the function to be compiled and
-may decide that it's just not worth it. In this case a status
-other than OK is passed back to the pipeline frontend.
-
-
-The easiest thing would be to abort pipeline processing and just
-give up. But this would remove the ability to trace the progress
-of the compiler (which better include failed compilations, too).
-So there is a special rule that odd priorities are still run,
-but even priorities are not. That's why e.g. -j trace
-registers itself with priority -99.
-
-
-
The Optimizer
-
-Maybe it hasn't become clear from the above description,
-but a module can attach any Lua or C function to the compiler
-pipeline. In fact all of the loadable modules are Lua modules.
-Only the backend itself is written in C.
-
-
-So, yes — the LuaJIT optimizer is written in pure Lua!
-
-
-And no, don't worry, it's quite fast. One reason for this is
-that a very simple abstract interpretation algorithm
-is used. It mostly ignores control flow and/or basic block
-boundaries.
-
-
-Thus the results of the analysis are really only hints.
-The backend must check the preconditions (the contracts)
-for these hints (e.g. the object type). Still, the generated
-hints are pretty accurate and quite useful to speed up the
-compiled code (see below).
-
-
-Explaining how abstract interpretation works is not within the
-scope for this short essay. You may want to have a look at the
-optimizer source code and/or read some articles or books on
-this topic. The canonical reference is
-» Principles of Program Analysis.
-Ok, so this one is a bit more on the theoretical side (a gross
-understatement). Try a search engine with the keywords "abstract
-interpretation", too.
-
-
-Suffice to say the optimizer generates hints and passes these
-on to the backend. The backend then decides to encode different
-forms for the same bytecode instruction, to combine several
-instructions or to inline code for C functions. If the hints
-from the optimizer are good, the resulting code will perform
-better because shorter code paths are used for the typical cases.
-
-
-
The JIT Advantage
-
-One important feature of the optimizer is that it takes 'live'
-function arguments into account. Since the JIT compiler is
-called just before the function is run, the arguments for this
-first invocation are already present. This can be used to great
-advantage in a dynamically typed language, such as Lua.
-
-
-Here's a trivial example:
-
-
-function foo(t, k)
- return t[k]
-end
-
-
-Without knowing the most likely arguments for the function
-there's not much to optimize.
-
-
-Ok, so 't' is most likely a table. But it could be userdata, too.
-In fact it could be any type since the introduction of generic
-metatables for types.
-
-
-And more importantly 'k' can be a number, a string
-or any other type. Oh and let's not forget about metamethods ...
-
-
-If you know a bit about Lua internals, it should be clear by now
-that the code for this function could potentially branch to half
-of the Lua core. And it's of course impossible to inline all
-these cases.
-
-
-On the other hand if it's known (or there's a good hint)
-that 't' is a table and that 'k' is a positive integer, then there
-is a high likeliness that the key 'k' is in the array part
-of the table. This lookup can be done with just a few machine code
-instructions.
-
-
-Of course the preconditions for this fast path have to be checked
-(unless there are definitive hints). But if the hints are right,
-the code runs a lot faster (about a factor of 3 in this case
-for the pure table lookup).
-
-
-
Optimizing the Optimizer
-
-A question that surely popped up in your mind while reading
-the above section: does the optimizer optimize itself? I.e.
-is the optimizer module compiled?
-
-
-The current answer is no. Mainly because the compiler pipeline
-is single-threaded only. It's locked during compilation and
-any parallel attempt to JIT compile a function results in
-a 'DELAYED' status code. In fact all modules that attach to
-the compiler pipeline disable compilation for the entire
-module (because LuaJIT would do that anyway). The main chunk
-of modules loaded with require() is never compiled,
-so there is no chicken-and-egg problem here.
-
-
-Of course you could do an AOT compilation in the main chunk of
-the optimizer module. But then only with the plain backend.
-Recompiling it later on with the optimizer attached doesn't work,
-because a function cannot be compiled twice (I plan to lift
-this restriction).
-
-
-The other question is whether it pays off to compile the optimizer
-at all? Honestly, I haven't tried, because the current optimizer
-is really simple. It runs very quickly, even under the bytecode
-interpreter.
-
-
-
That's All Folks
-
-Ok, that's all for now. I'll extend this text later on with
-new topics that come up in questions. Keep on asking these
-on the mailing list if you are interested.
-
-As is always the case with benchmarks, care must be taken to
-interpret the results:
-
-
-First, the standard Lua interpreter is already very fast.
-It's commonly the fastest of it's class (interpreters) in the
-» Great Computer Language Shootout.
-Only true machine code compilers get a better overall score.
-
-
-Any performance improvements due to LuaJIT can only be incremental.
-You can't expect a speedup of 50x if the fastest compiled language
-is only 5x faster than interpreted Lua in a particular benchmark.
-LuaJIT can't do miracles.
-
-
-Also please note that most of the benchmarks below are not
-trivial micro-benchmarks, which are often cited with marvelous numbers.
-Micro-benchmarks do not realistically model the performance gains you
-can expect in your own programs.
-
-
-It's easy to make up a few one-liners like:
- local function f(...) end; for i=1,1e7 do f() end
-This is more than 30x faster with LuaJIT. But you won't find
-this in a real-world program.
-
-
-
Measurement Methods
-
-All measurements have been taken on a Pentium III 1.139 GHz
-running Linux 2.6. Both Lua and LuaJIT have been compiled with
-GCC 3.3.6 with -O3 -fomit-frame-pointer.
-You'll definitely get different results on different machines or
-with different C compiler options. *
-
-
-The base for the comparison are the user CPU times as reported by
-/usr/bin/time. The runtime of each benchmark is parametrized
-and has been adjusted to minimize the variation between several runs.
-The ratio between the times for LuaJIT and Lua gives the speedup.
-Only this number is shown because it's less dependent on a specific system.
-
-
-E.g. a speedup of 6.74 means the same benchmark runs almost 7 times
-faster with luajit -O than with standard Lua (or with
--j off). Your mileage may vary.
-
-
-* Yes, LuaJIT relies on quite a bit of the Lua core infrastructure
-like table and string handling. All of this is written in C and
-should be compiled with full optimization turned on, or performance
-will suffer.
-
-Note that many of these benchmarks have changed over time (both spec
-and code). Benchmark results shown in previous versions of LuaJIT
-are not directly comparable. The next section compares different
-versions with the current set of benchmarks.
-
-
-
Comparing LuaJIT Versions
-
-This shows the improvements between the following versions:
-
-
-
LuaJIT 1.0.x
-
LuaJIT 1.1.x
-
-
-
-
-
-
Benchmark
-
Speedup
-
-
-
-
-
-
fannkuch
-
3.96 → 5.37
-
-
-
-
chameneos
-
2.25 → 5.08
-
-
-
-
nsievebits
-
2.90 → 5.05
-
-
-
-
pidigits
-
3.58 → 4.94
-
-
-
-
nbody
-
4.16 → 4.63
-
-
-
-
cheapconcr
-
1.46 → 4.46
-
-
-
-
partialsums
-
1.71 → 3.73
-
-
-
-
fasta
-
2.37 → 2.68
-
-
-
-
cheapconcw
-
1.27 → 2.52
-
-
-
-
revcomp
-
1.45 → 1.92
-
-
-
-
knucleotide
-
1.32 → 1.59
-
-
-
-
-
-All other benchmarks show only minor performance differences.
-
-
-
Summary
-
-These results should give you an idea about what speedup
-you can expect depending on the nature of your Lua code:
-
-
-
-LuaJIT is really good at (floating-point) math and loops
-(mandelbrot, pidigits, spectralnorm, partialsums).
-
-
-Function calls (recursive), vararg calls, table lookups (nbody),
-table iteration and coroutine switching (chameneos, cheapconc)
-are a lot faster than with plain Lua.
-
-
-It's still pretty good for indexed table access (fannkuch, nsieve)
-and string processing (fasta, revcomp, knucleotide).
-But there is room for improvement in a future version.
-
-
-If your application spends most of the time in C code
-you won't see much of a difference (regexdna, sumfile).
-Ok, so write more code in pure Lua. :-)
-
-
-The real speedup may be shadowed by other dominant factors in a benchmark:
-
-
Common parts of the Lua core: e.g. memory allocation
-and GC (binarytrees).
-
Language characteristics: e.g. lack of bit operations (nsievebits).
-
System characteristics: e.g. CPU cache size and memory speed (nsieve).
-
-
-
-
-The best idea is of course to benchmark your own applications.
-Please report any interesting results you may find. Thank you!
-
-LuaJIT has only a single stand-alone executable, called luajit.
-It can be used to run simple Lua statements or whole Lua applications
-from the command line. It has an interactive mode, too.
-
-
-Note: The optimizer is not activated by default because it resides
-in an external module
-(see Installing LuaJIT).
-It's recommended to always use the optimizer, i.e.:luajit -O
-
-
-
Command Line Options
-
-The luajit stand-alone executable is just a slightly modified
-version of the regular lua stand-alone executable.
-It supports the same basic options, too. Please have a look at the
-Manual Page
-for the regular lua stand-alone executable.
-
-
-Two additional options control LuaJIT behaviour:
-
-
-
-j cmd[=value]
-
-This option performs a LuaJIT control command. LuaJIT has a small
-but extensible set of control commands. It's easy to add your own.
-
-
-The command is first searched for in the jit.* library.
-If no matching function is found, a module named jit.<cmd>
-is loaded. The module table must provide a start() function.
-
-
-For the -j cmd form the function is called without an argument.
-Otherwise the value is passed as the first argument (a string).
-
-
-Here are the built-in LuaJIT control commands:
-
-
-
-j on — Turns the JIT engine on (default).
-
-j off — Turns the JIT engine off.
-
-j debug[=level] — Set debug level. See
-jit.debug().
-
-
-The following control commands are loaded from add-on modules:
-
-
-
-j trace[=file] — Trace the progress of the JIT compiler.
-
-j dumphints[=file] — Dump bytecode + hints before compilation.
-
-j dump[=file] — Dump machine code after compilation.
-
-
-
-
-O[level]
-
-This option loads and runs the optimizer module jit.opt.
-The optimizer generates hints for the compiler backend to improve
-the performance of the compiled code. The optimizer slows down
-compilation slightly, but the end result should make up for it
-in almost every case.
-
-
-The -O form sets the default optimizer level, which is
-currently 2 (this may change in future versions
-of LuaJIT).
-
-
-The -Olevel form explicitly sets the optimizer level:
-
-
-
-O0 — disable the optimizer but leave it attached.
-
-O1 — perform standard optimizations (like hints for table lookups).
-
-O2 — like -O1 but also loads jit.opt_inline to enable result hints and inlining for standard library functions.
-
-
-
