The LuaJIT Wiki

not logged in | [Login]

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.


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