LuaVela 0.22 Lua API Reference¶
- Functions
ujit.coverage.start
ujit.coverage.stop
ujit.coverage.pause
ujit.coverage.unpause
ujit.dump.bc
ujit.dump.bcins
ujit.dump.mcode
ujit.dump.stack
ujit.dump.start
ujit.dump.stop
ujit.dump.trace
ujit.getmetrics
ujit.immutable
ujit.memprof.start
ujit.memprof.stop
ujit.profile.available
ujit.profile.init
ujit.profile.start
ujit.profile.stop
ujit.profile.terminate
ujit.seal
ujit.table.keys
ujit.table.shallowcopy
ujit.table.size
ujit.table.toset
ujit.table.values
ujit.usesfenv
Functions¶
Note
Please note that any function from the list below may be hidden from the end users if sandboxing mechanism is used.
ujit.coverage.start
¶
local started = ujit.coverage.start(filename[, excludes])
Starts platform-level coverage counting and streams output to filename
. excludes
array with regexps can be optionally passed to exclude filenames from coverage output. Returns true
on success and false
on any error.
ujit.coverage.stop
¶
ujit.coverage.stop()
Stops platform-level coverage counting. Does nothing if coverage was not enabled. Does not have a return value.
ujit.coverage.pause
¶
ujit.coverage.pause()
Pauses streaming of coverage counting output into file. Does nothing if coverage was not enabled or was already paused. Does not have a return value.
ujit.coverage.unpause
¶
ujit.coverage.unpauses()
Unpauses streaming of coverage counting output info file. Does nothing if coverage was not enabled or was already unpaused. Does not have a return value.
ujit.dump.bc
¶
ujit.dump.bc(io_object, func)
Dumps bytecode of the function func
to io_object
. Throws an error if io_object
is not of appropriate type or if func
is not a function. Does not have a return value.
ujit.dump.bcins
¶
local dumped = ujit.dump.bcins(io_object, func, pc[, nest_level])
Dumps pc
-th bytecode of the function func
to io_object
. pc
is 0-based. If nest_level
is specified, prepends the output with corresponding indentation. Throws an error if io_object
is not of appropriate type or if func
is not a function. Returns true
if data was dumped, and false
otherwise.
ujit.dump.mcode
¶
ujit.dump.mcode(io_object, trace_no)
Dumps machine code for the trace trace_no
to io_object
. Throws an error if io_object
is not of appropriate type. Does not have a return value.
ujit.dump.stack
¶
ujit.dump.stack(io_object)
Dumps the Lua stack of currently executed coroutine to io_object
. If any error occurs, dumps nothing. Never throws a run-time error.
ujit.dump.start
¶
local started, fname_real = ujit.dump.start([fname_stub])
Starts dumping the progress of the JIT compiler to fname_stub
suffixed with some random extension. started
is set to true
if dumping was started, and false
otherwise. The resulting dump file name is returned to fname_real
if dumping was actually started. If fname_stub
is omitted or passed as "-"
, dumping is started to standard output, and fname_real
is set to "-"
, too.
ujit.dump.stop
¶
local stopped = ujit.dump.stop()
Stops dumping the progress of the JIT compiler. Returns true
if stop was successful, and false
otherwise.
ujit.dump.trace
¶
ujit.dump.trace(io_object, trace_no)
Dumps IR for the trace trace_no
to io_object
. Throws an error if io_object
is not of appropriate type. Does not have a return value.
ujit.getmetrics
¶
local metrics = ujit.getmetrics()
Returns a table with the current values of LuaVela-specific metrics. The table has following keys:
Key Description strnum Current number of string
objects.tabnum Current number of table
objects.udatanum Current number of userdata
objects.gc_total Current number of bytes used by non-sealed objects and all strings (both sealed and non-sealed). gc_sealed Current number of sealed objects excluding strings. gc_freed Number of freed bytes since the last retrieval of metrics. gc_allocated Number of allocated bytes since the last retrieval of metrics. gc_steps_pause Number of GC’s pause
phases since the last retrieval of metrics.gc_steps_propagate Number of GC’s propagate
phases since the last retrieval of metrics.gc_steps_atomic Number of GC’s atomic
phases since the last retrieval of metrics.gc_steps_sweepstring Number of GC’s sweepstring
phases since the last retrieval of metrics.gc_steps_sweep Number of GC’s sweep
phases since the last retrieval of metrics.gc_steps_finalize Number of GC’s finalize
phases since the last retrieval of metrics.jit_snap_restore Number of snapshot restorations since the last retrieval of metrics. strhash_hit Number of hits to the internal string storage since the last retrieval of metrics. strhash_miss Number of misses to the internal string storage since the last retrieval of metrics.
ujit.immutable
¶
local value = ujit.immutable(value)
Makes an object immutable and returns a reference to it for convenience. See here for details.
ujit.memprof.start
¶
local started, fname_real = ujit.memprof.start(interval, fname_stub)
Starts memory profiling for interval
seconds.If interval
is 0, profiling runs until ujit.memprof.stop
is called. Data are streamed to fname_stub
suffixed with some random extension. started
is set to true
if profiling was started, and false
otherwise. Upon successful start, the resulting full profile file name is returned in fname_real
.
ujit.memprof.stop
¶
local stopped = ujit.memprof.stop()
Stops memory profiling started by ujit.memprof.start
. Returns true
on success and false
otherwise.
ujit.profile.available
¶
local available = ujit.profile.available()
Returns true
if LuaVela-level profiler is available, and false
otherwise.
ujit.profile.init
¶
local initialized = ujit.profile.init()
Returns true
if LuaVela-level profiler was successfully initialized, and false
otherwise. Profiler cannot be used prior to initialization.
ujit.profile.start
¶
local started, fname_real = ujit.profile.start(interval, mode[, fname_stub])
Starts profiling in mode
with sampling interval
(expressed in microseconds). Depending on the mode
, may stream profile data to fname_stub
suffixed with some random extension. started
is set to true
if profiling was started, and false
otherwise. The resulting full profile file name is returned in fname_real
if applicable (see below). Supported values for mode
are:
Value Description "default"
Collects only lightweight in-memory per-VM state profile. fname_stub
is ignored,fname_real
is always set tonil
."leaf"
Collects leaf profile. fname_stub
must be specified. If profiling was started, the profile will be streamed tofname_real
."callgraph"
Collects full call-graph profile. fname_stub
must be specified. If profiling was started, the profile will be streamed tofname_real
.
ujit.profile.stop
¶
local counters[, err_reason] = ujit.profile.stop()
On success, stops profiling and returns a table with in-memory VM counters. On failure, returns nil
as the first argument and an error reason string as the second argument.
ujit.profile.terminate
¶
local terminated = ujit.profile.terminate()
Returns true
if LuaVela-level profiler was successfully terminated, and false
otherwise. Profiler cannot be used after termination.
ujit.seal
¶
ujit.seal(obj)
Recursively seals obj
. Throws a run-time error if sealing could not be finalized. In case of any errors, the state of obj
is guaranteed to be the same as it was prior to the call to this interface. See here for details.
ujit.table.keys
¶
local new_table = ujit.table.keys(table)
Returns a new table with source table
keys as values. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table. Implementation detail (not guaranteed in future versions): Returned table is a sequence.
ujit.table.shallowcopy
¶
local new_table = ujit.table.shallowcopy(table)
Returns a shallow copy of table
. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table.
ujit.table.size
¶
local table = {1, 2, nil, 3, key = "value" }
print(ujit.table.size(t)) -- 4
Returns number of non-nil elements in a table (both array and hash part).
ujit.table.toset
¶
local new_table = ujit.table.toset(table)
Returns a new table with source table
values as keys and values set to true
. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table.
ujit.table.values
¶
local new_table = ujit.table.values(table)
Returns a new table with source table
values as values. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table. Implementation detail (not guaranteed in future versions): Returned table is a sequence.
ujit.usesfenv
¶
local uses_fenv = ujit.usesfenv(func)
Checks if a function func
uses its environment. Following logic applies:
For regular Lua functions, returns
true
if the function meets at least one of following conditions (andfalse
otherwise):
- It references at least one global variable.
- It references at least one upvalue.
For built-in functions, always returns
false
.For registered C functions, always returns
true
.