LuaVela 0.24 Lua API Reference (devel)¶
Functions¶
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 more details.
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 more details.
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
.
Modules¶
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.
stop
¶
ujit.coverage.stop()
Stops platform-level coverage counting. Does nothing if coverage was not enabled. Does not have a return value.
ujit.debug¶
gettableinfo
¶
local info = ujit.debug.gettableinfo(table)
Returns a table info
containing internal characteristics of table. info
provides following fields:
Field Description acapacity Capacity of the array part of table asize Number of elements stored in the array part of table hcapacity Capacity of the hash part of table hmaxchain Length of the longest chain in the hash part of table hgchains Number of chains in the hash part of table (1-element chains are included, too) hsize Number of elements stored in the hash part of table
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.
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.
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.
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.
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.math¶
All functions in this module treat arguments as standard Lua’s math
functions:
- All extra arguments are ignored.
- For the first argument, all non-number values except
- coercible strings throw.
- Coercible strings are coerced to numbers and
- corresponding conversion results are processed regularly. Strings “nan”, “infinity”, “inf”, “+inf”, “-inf” (all case-insensitive) are coercible.
- Non-coercible strings throw.
isfinite
¶
local isfinite_x = ujit.math.isfinite(42) -- true
local isfinite_y = ujit.math.isfinite(math.huge) -- false
Returns false
if number is NaN, negative or positive infinity. Returns true
otherwise.
isinf
¶
local isinf_x = ujit.math.isinf(42) -- false
local isinf_y = ujit.math.isinf(math.huge) -- true
local isinf _z= ujit.math.isinf(-math.huge) -- true
Returns true
if number is positive or negative infinity and false
otherwise.
isnan
¶
local isnan_x = ujit.math.isnan(42) -- false
local isnan_y = ujit.math.isnan(math.huge) -- false
local isnan_z = ujit.math.isnan(ujit.math.nan) -- true
local isnan_z2 = ujit.math.isnan(0 / 0) -- true
Returns true
is number is NaN and false
otherwise.
isninf
¶
local isninf_x = ujit.math.isninf(42) -- false
local isninf_y = ujit.math.isninf(math.huge) -- false
local isninf_z = ujit.math.isninf(-math.huge) -- true
Returns true
if number is negative infinity and false
otherwise.
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 is being 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.profile¶
available
¶
local available = ujit.profile.available()
Returns true if LuaVela-level profiler is available, and false otherwise.
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.
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.string¶
trim
¶
local s = ujit.string.trim(" \t\n hello \r\n") -- "hello"
Removes whitespace from both ends of the string.
split
¶
local t = {}
for token in ujit.string.split("a,b,c", ",") do
table.insert(t)
end
-- t == { "a", "b", "c" }
Returns an iterator that can be used in for
loops. The separator should be non-empty plain text string (characters like \n
and \0
are supported for separators). Treats consecutive separators as if they have empty token between them, for example:
local t = {}
for token in ujit.string.split("a,,c", ",") do
table.insert(t, token)
end
-- t == { "a", "", "c" }
Separators at the beginning/end of the string are treated as if there was an empty token in the beginning/end of the string, for example:
local t = {}
for token in ujit.string.split(",a,,c,", ",") do
table.insert(t, token)
end
-- t == { "", "a", "", "c", "" }
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.
rindex
¶
local table = {x = {y = {z = "foo"}}}
local value1 = ujit.table.rindex(table, "x", "y", "z") -- foo
local value2 = ujit.table.rindex(table, "x", "A", "z") -- nil
Indexes table
“recursively”. If the look up fails at some point, returns nil
without raising an error. Respects metamethods.
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.
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).