LuaVela 0.22 C API Reference¶

Header Files ¶

`<ujit/lextlib.h>`¶

#include <ujit/lextlib.h>

Main header file for LuaVela’s extended C API. Please include it to access all functions, data structures and constants documented below.

Functions ¶

`luaE_coveragestart`¶

int luaE_coveragestart(lua_State *L, const char *filename, const char **excludes, size_t num);

Starts platform-level coverage counting for the state L and dumps output into filename. Regexps for excluding files from coverage can be passed with excludes, num corresponds to the number of passed regexps. Returns LUA_COV_SUCCESS on success and LUA_COV_ERROR in case of any error.

`luaE_coveragestart_cb`¶

int luaE_coveragestart_cb(lua_State *L, lua_Coveragewriter cb, void *context, const char **excludes, size_t num);

Same as luaE_coveragestart, but outputs through provided lua_Coveragewriter callback.

`luaE_coveragestop`¶

int luaE_coveragestop(lua_State *L)

Stops platform-level coverage counting for the state L. Returns LUA_COV_SUCCESS on success and LUA_COV_ERROR in case of any error.

`luaE_createstate`¶

lua_State *luaE_createstate(const struct luaext_Options *opt);

Creates a new state with the options specified in opt. Superset of the standard lua_newstate and luaL_newstate, as well as the extended luaE_newdataslave.

`luaE_deepcopytable`¶

void luaE_deepcopytable(lua_State *to, lua_State *from, int idx)

Creates a deep copy of table at idx in from state and pushes it on the top of a stack of to state. Table may contain only booleans, numbers, strings, tables and Lua functions without upvalues and accesses to globals.

`luaE_dumpbc`¶

void luaE_dumpbc(lua_State *L, int idx, FILE *out);

Dumps the byte code of the functional object located at idx to out. If idx is not a functional object, does nothing.

`luaE_dumpbcsource`¶

void luaE_dumpbcsource(lua_State *L, int idx, FILE *out, int hl_bc_pos);

Same as luaE_dumpbc, but also prints source code corresponding to byte codes (similar to 'disassembly /s’ in gdb). Highlights byte code with index hl_bc_pos with “->” (no byte code gets highlighted if hl_bc_pos = -1).

`luaE_dumpstart`¶

int luaE_dumpstart(const lua_State *L, FILE *out);

Starts dumping JIT compiler’s progress to out. Returns 0 if dumping was started successfully, and a non-0 value otherwise.

`luaE_dumpstop`¶

int luaE_dumpstop(const lua_State *L);

Stops dumping JIT compiler’s progress. Returns 0 if dumping was started successfully, and a non-0 value otherwise.

`luaE_getdataroot`¶

void luaE_getdataroot(lua_State *L);

For the regular state L, pushes data state’s data root on top of L’s stack. See also luaE_setdataroot.

`luaE_immutable`¶

void luaE_immutable(lua_State *L, int idx);

Makes an object at idx immutable. See here for details.

`luaE_intinit`¶

int luaE_intinit(int signo);

Global initialization of timer interrupts. Signal with the number signo will be used to deliver interrupts to the process with some pre-defined interval. Returns LUA_INT_SUCCESS on success, LUA_INT_ERR otherwise (e.g. initialization is already performed). This function must be called prior to usage of any facilities provided by the API for coroutine timeouts.

`luaE_intresolvable`¶

int luaE_intresolvable(const struct timeval *timeout);

Returns a non-0 value if a timeout value has resolution greater than or equal to the one provided by the timer interrupts. Otherwise returns 0.

`luaE_intterm`¶

int luaE_intterm(void);

Global termination of timer interrupts. Termination is performed only if the timer interrupts were initialized. Returns LUA_INT_SUCCESS on success, LUA_INT_ERR otherwise. Facilities provided by the API for coroutine timeouts must not be used after calling this function.

`luaE_iterate`¶

uint64_t luaE_iterate(lua_State *L, int idx, uint64_t iter_state);

Pushes on stack the next key-value pair from the table stored at idx and returns a new value of the internal iterator state for subsequent calls. If the entire table is traversed, does not touch the stack and returns LUA_ITER_END. For the first invocation, iter_state must be set to LUA_ITER_BEGIN. Please note that the calling code must not use iter_state as well as the return value for anything but passing it back to this function.

Usage example:

uint64_t iter = LUA_ITER_BEGIN;
while ((iter = luaE_iterate(L, index, iter)) != LUA_ITER_END) {
    /* Key is located at index -2 (2nd top-most element on the stack) */
    /* Value is located at index -1 (the top-most element on the stack) */
    lua_pop(L, 2); /* remove key-value pair from the stack before the next iteration */
}

`luaE_metrics`¶

struct lua_Metrics luaE_metrics (lua_State *L);

Returns a structure containing numerous runtime metrics of the state. Please find the definition of struct lua_Metrics in the Types section.

`luaE_newdataslave`¶

lua_State *luaE_newdataslave(lua_State *datastate);

Creates a new Lua state which uses datastate for accessing the global data feed. NB! This interface is deprecated in favor of luaE_createstate.

`luaE_profavailable`¶

int luaE_profavailable(void);

Returns LUA_PROFILE_SUCCESS if profiling is available and LUA_PROFILE_ERR otherwise.

`luaE_profinit`¶

int luaE_profinit(void);

Global profiler initialization. Returns LUA_PROFILE_SUCCESS on success, LUA_PROFILE_ERR otherwise (e.g. initialization is already performed). This function must be called prior to usage of any other facilities provided by the profiler (except luaE_profavailable).

`luaE_profterm`¶

int luaE_profterm(void);

Global profiler termination. Termination is performed only if the profiler was initialized and is in a non-running state at the time of the call. Returns LUA_PROFILE_SUCCESS on success, LUA_PROFILE_ERR otherwise. No other facilities provided by the profiler must be used after calling this function (except luaE_profavailable and luaE_profinit).

`luaE_requiref`¶

void luaE_requiref(lua_State *L, const char *modname, lua_CFunction openf);

Calls function openf with string modname as an argument and sets the call result in package.loaded[modname], as if that function has been called through require. Leaves a copy of that result on the stack. This function implements a subset of luaL_requiref available since Lua 5.2 and will be deprecated once LuaVela becomes fully 5.2-compatible.

`luaE_seal`¶

void luaE_seal(lua_State *L, int index);

Recursively seals a value at the given acceptable index. The value must be a table, string, function or function prototype. For the function, its prototype is also sealed. For the table, all keys, values and array slots are also sealed. Attempt to seal a function with upvalues results in an error.

`luaE_setdataroot`¶

void luaE_setdataroot(lua_State *L, int idx);

For the data state L, sets the table at idx as its data root. See also luaE_getdataroot.

`luaE_settimeout`¶

int luaE_settimeout(lua_State *L, const struct timeval *timeout, int restart);

Sets a timeout for the coroutine L. If the restart flag is set to a non-zero value, the new timeout value is applied immediately. Returns LUA_TIMEOUT_SUCCESS on success, and one of LUA_TIMEOUT_ERR* status codes otherwise (see below). If coroutine terminates because of timeout, lua_resume returns LUA_TIMEOUT status. Such coroutines cannot be resumed.

`luaE_settimeoutf`¶

lua_CFunction luaE_settimeoutf(lua_State *L, lua_CFunction timeoutf);

Sets a new function to be called in case of coroutine timeout and returns the old one. If a coroutine terminates because of timeout, the timeout function timeoutf is called in the context of the coroutine before its stack is unwound. Currently, a call to timeoutf is not protected. timeoutf can return any fixed number of arguments (i.e. LUA_MULTRET cannot be returned).

`luaE_shallowcopytable`¶

void luaE_shallowcopytable(lua_State *L, int idx);

Creates a shallow copy of a table at idx and pushes it on stack. Metatable of the table is not copied. Throws a runtime error in case an element at idx is not a table.

`luaE_tablekeys`¶

void luaE_tablekeys(lua_State *L, int idx);

Creates a new table from table at idx with source table keys as values and pushes it on stack. Metatable of the table is not copied. Throws a runtime error in case an element at idx is not a table. Implementation detail (not guaranteed in future versions): Created table is a sequence.

`luaE_tabletoset`¶

void luaE_tabletoset(lua_State *L, int idx);

Creates a new table from table at idx with source table values as keys and values set to true and pushes it on stack. Metatable of the table is not copied. Throws a runtime error in case an element at idx is not a table.

`luaE_tablevalues`¶

void luaE_tablevalues(lua_State *L, int idx);

Creates a new table from table at idx with source table values as values and pushes it on stack. Metatable of the table is not copied. Throws a runtime error in case an element at idx is not a table. Implementation detail (not guaranteed in future versions): Created table is a sequence.

`luaE_totalmem`¶

size_t luaE_totalmem(void);

Returns a total number of bytes requested by LuaVela’s allocator from operating system.

`luaE_usesfenv`¶

int luaE_usesfenv(lua_State *L, int idx);

Checks if a function at idx uses its environment. Following logic applies:

For regular Lua functions, returns a non-zero value if the function meets at least one of following conditions (and 0 otherwise):

It references at least one global variable.

It references at least one upvalue.

For built-in functions, always returns 0.

For registered C functions, always returns a non-zero value.

`luaE_verstring`¶

const char *luaE_verstring(void);

Returns a string describing current LuaVela version.

`luaopen_bit`¶

int luaopen_bit(lua_State *L);

Opens the bit library, an extension to the Lua standard libraries. This function is called by luaL_openlibs as well, so no need to call it explicitly if you use luaL_openlibs.

`luaopen_ffi`¶

int luaopen_ffi(lua_State *L);

Opens the ffi library, an extension to the Lua standard libraries. This function is called by luaL_openlibs as well, so no need to call it explicitly if you use luaL_openlibs.

`luaopen_jit`¶

int luaopen_jit(lua_State *L);

Opens the jit library, an extension to the Lua standard libraries. This function is called by luaL_openlibs as well, so no need to call it explicitly if you use luaL_openlibs.

`luaopen_ujit`¶

int luaopen_ujit(lua_State *L);

Opens the ujit library, an extension to the Lua standard libraries. This function is called by luaL_openlibs as well, so no need to call it explicitly if you use luaL_openlibs.

Types ¶

`lua_Coveragewriter`¶

typedef void (*lua_Coveragewriter) (void *context, const char *lineinfo, size_t size);

Callback for streaming line information in platform-level coverage counting. Should accept three arguments: pointer to callback-specific context, const char pointer to coverage lineinfo message and size of the message.

`lua_Metrics`¶

struct _Metrics {
    size_t strnum;
    size_t tabnum;
    size_t strhash_hit;

    size_t strhash_miss;

    size_t udatanum;
    size_t gc_total;
    size_t gc_sealed;
    size_t gc_freed;
    size_t gc_allocated;
    size_t gc_steps_pause;
    size_t gc_steps_propagate;
    size_t gc_steps_atomic;
    size_t gc_steps_sweepstring;
    size_t gc_steps_sweep;
    size_t gc_steps_finalize;
    size_t jit_snap_restore;

    size_t jit_mcode_size;

    unsigned int jit_trace_num;
};

Various runtime metrics.

`luaext_HashF`¶

enum luaext_HashF { ... };

Hashing functions used for string interning across the platform:

LUAEXT_HASHF_DEFAULT: Implementation-defined default;

LUAEXT_HASHF_MURMUR: murmur hashing function.

`luaext_Options`¶

struct luaext_Options {
        lua_State         *datastate;
        lua_Alloc          allocf;
        void              *allocud;
        enum luaext_HashF hashf;
};

Options for creating a new VM instance:

datastate: Pointer to data master of the created state (or NULL if not applicable);

allocf: Allocator’s function (see lua_newstate for more details). If set to NULL, implementation-defined default allocator will be used;

allocud: Opaque allocator’s state (see lua_newstate for more details);

hashf: Hashing functions used for string interning across the platform. NB! This parameter is ignored if datastate is not NULL;

Note. Following statement creates a structure with all options set to their default values:

struct luaext_Options opt = {0};

Extended Thread Statuses ¶

`LUA_TIMEOUT`¶

Returned by lua_resume in case of coroutine timeout.

Constants ¶

`LUA_BITLIBNAME`¶

Name of the bit library: "bit".

`LUA_COV_ERROR`¶

Generic error code for platform-level coverage counting.

`LUA_COV_SUCCESS`¶

Generic success code for platform-level coverage counting.

`LUA_FFILIBNAME`¶

Name of the ffi library: "ffi".

`LUA_INT_ERR`¶

Generic error code for timer interrupts.

`LUA_INT_SUCCESS`¶

Generic success code for timer interrupts.

`LUA_ITER_BEGIN`¶

Initial iterator state for luaE_iterate, should be passed on the first call to the function.

`LUA_ITER_END`¶

Final iterator state for luaE_iterate, returned when table traversal is finished.

`LUA_JITLIBNAME`¶

Name of the jit library: "ujit".

`LUA_PROFILE_ERR`¶

Generic error code for profiler’s interfaces.

`LUA_PROFILE_ERRIO`¶

I/O error occurred during profiling.

`LUA_PROFILE_ERRMEM`¶

Memory error occurred during profiling.

`LUA_PROFILE_SUCCESS`¶

Generic success code for profiler’s interfaces.

`LUA_TIMEOUT_ERRABORT`¶

Coroutine is in a non-runnable state at the time of the call to luaE_settimeout. For example, you try to set a timeout for a coroutine which was resumed and threw an error during execution.

`LUA_TIMEOUT_ERRBADTIME`¶

Malformed const struct timeval *timeout was passed to luaE_settimeout. Currently following values are considered malformed:

NULL.

non-NULL pointer pointing to a struct with at least one member with a negative value.