Non-public jit.* API

LuaJIT has some undocumented facilities for tracing program execution and what the trace compiler is doing. What follows is a bit rough, inaccurate, subject to change and very incomplete. There's probably a good reason this is undocumented.

These functions are used in several of the -j library files. dump.lua is probably a good place to start.

jit.attach

You can attach callbacks to a number of compiler events with jit.attach. The callback can be called:

• when a function has been compiled to bytecode ("bc");
• when trace recording starts or stops ("trace");
• as a trace is being recorded ("record");
• or when a trace exits through a side exit ("texit").

Set a callback with jit.attach(callback, "event") and clear the same callback with jit.attach(callback)

The arguments passed to the callback depend on the event being reported:

• "bc": callback(func). func is the function that's just been recorded.
• "trace": callback(what, tr, func, pc, otr, oex)
  • what is a description of the trace event: "flush", "start", "stop", "abort". Available for all events.
  • tr is the trace number. Not available for flush.
  • func is the function being traced. Available for start and abort.
  • pc is the program counter - the bytecode number of the function being recorded (if this a Lua function). Available for start and abort.
  • otr start: the parent trace number if this is a side trace, abort: abort code (integer)?
  • oex start: the exit number for the parent trace, abort: abort reason (string)
• "record": callback(tr, func, pc, depth). The first arguments are the same as for trace start. depth is the depth of the inlining of the current bytecode.
• "texit": callback(tr, ex, ngpr, nfpr).
  • tr is the trace number as before
  • ex is the exit number
  • ngpr and nfpr are the number of general-purpose and floating point registers that are active at the exit.

jit.util.funcinfo(func, pc)

When passed func and pc from a jit.attach callback, jit.util.funcinfo returns a table of information about the function, much like debug.getinfo.

The fields of the table are:

• linedefined: as for debug.getinfo
• lastlinedefined: as for debug.getinfo
• params: the number of parameters the function takes
• stackslots: the number of stack slots the function's local variable use
• upvalues: the number of upvalues the function uses
• bytecodes: the number of bytecodes it the compiled function
• gcconsts: ??
• nconsts: ??
• currentline: as for debug.getinfo
• isvararg: if the function is a vararg function`
• source: as for debug.getinfo
• loc: a string describing the source and currentline, like "<source>:<line>"
• ffid: the fast function id of the function (if it is one). In this case only upvalues above and addr below are valid
• addr: the address of the function (if it is not a Lua function). If it's a C function rather than a fast function, only upvalues above is valid