LuaVela 0.20 Lua API Reference¶

Note

Please note that any function from the list below may be hidden from the end users if sandboxing mechanism is used.

Functions ¶

`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.unpause()

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 to nil.

"leaf"

Collects leaf profile. fname_stub must be specified. If profiling was started, the profile will be streamed to fname_real.

"callgraph"

Collects full call-graph profile. fname_stub must be specified. If profiling was started, the profile will be streamed to fname_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 successful 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.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 (and false 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.