Detailed Description

balua.h provides the public C API for creating, destroying, and configuring a BAS Lua/LSP VM.

Access the VM only while holding its server mutex, including calls from application C code. Lua-entered bindings already hold it. APIs that allocate Lua objects may raise Lua errors; use protected Lua calls where required. Shutdown must stop all users before destroying the VM and borrowed resources.

Creating and initializing a BAS Lua VM consists of calling balua_create() and calling balua_loadconfig().

See the C startup source code for the two following examples for more information on how to initialize the LSP plugin:

Collaboration diagram for Lua embedding and bindings:

Modules
	Weak Table reference
	Functions designed to be similar to using luaL_ref(L, LUA_REGISTRYINDEX), lua_rawgeti(L, LUA_REGISTRYINDEX, ix), and luaL_unref(L, LUA_REGISTRYINDEX, ix), but with weak references.

	Auxiliary API
	Optional bindings implemented in xrc/lua and declared in inc/lxrc.h.

Classes
struct	BaLua_param
	Startup and runtime parameters for a BAS Lua VM. More...

struct	LHttpDir
	LHttpDir is the HttpDir instance used by Lua bindings and can be used by advanced Lua bindings creating new HttpDir type Lua interfaces. More...

Macros
#define	balua_create(p) _balua_create(p, BALUA_VERSION)
	Create a BAS Lua VM. More...

#define	balua_getmutex(L) balua_getparam(L)->mutex
	Get the SoDisp mutex associated with the Lua VM. More...

#define	BA_LUA_DECLARE_MUTEX(name, L) ThreadMutex* name = baluaENV_getmutex(L)
	Declare a borrowed server mutex pointer from a BAS Lua binding state. More...

#define	balua_releasemutex(m) if(m) ThreadMutex_release(m)
	Release mutex m if it is not NULL. More...

#define	balua_setmutex(m) if(m) ThreadMutex_set(m)
	Acquire mutex m, waiting if necessary. More...

Typedefs
typedef struct LHttpDir	LHttpDir
	LHttpDir is the HttpDir instance used by Lua bindings and can be used by advanced Lua bindings creating new HttpDir type Lua interfaces. More...

Functions
BA_API void *	baLMalloc (lua_State *L, size_t size)
	Allocate application memory, retrying after a full Lua GC on allocation failure. More...

BA_API void *	baLRealloc (lua_State L, void p, size_t size)
	Resize application memory, retrying after a full Lua GC on allocation failure. More...

BA_API char *	baLStrdup (lua_State L, const char str)
	Duplicate a string using baLMalloc, including its full-GC retry on failure. More...

BA_API lua_State *	_balua_create (const BaLua_param *p, int version)
	Create a BAS Lua VM. More...

BA_API void	balua_close (lua_State *L)
	Close the BAS Lua VM, run finalizers, and free its copied parameters. More...

BA_API int	balua_usertracker_create (lua_State *L, U32 noOfLoginTrackerNodes, U32 maxNumberOfLogins, BaTime banTime)
	Install Lua bindings for the default login tracker. More...

BA_API lua_State *	balua_getmainthread (lua_State *L)
	Get the main state without changing the stack. More...

BA_API BaLua_param *	balua_getparam (lua_State *L)
	Get the VM's stored parameter copy without changing the stack. More...

BA_API int	balua_loadfile (lua_State L, const char filename, struct IoIntf *io, int envix)
	Compile a Lua source or bytecode file without executing it. More...

BA_API void	balua_getuservalue (lua_State *L, int index)
	Pushes onto the stack the first user value associated with the full userdata at the given index. More...

BA_API int	balua_loadconfig (lua_State L, struct IoIntf io, const char *filename)
	Load a Lua script and run the script at startup. More...

BA_API int	balua_loadconfigExt (lua_State L, struct IoIntf io, const char *filename, int nresults)
	Load a Lua script and run the script at startup. More...

BA_API IoIntf *	balua_iointf (lua_State L, const char name, struct IoIntf *newio)
	Register an IoIntf instance with the Lua VM. More...

BA_API struct IoIntf **	balua_createiointf (lua_State *L)
	Push a Lua I/O userdata whose underlying interface is owned by Lua. More...

BA_API void	balua_ubjson (lua_State *L)
	Install the UBJSON Lua API. More...

BA_API int	baCheckZipSignature (const U8 pubKey, U32 fileSize, struct CspReader reader)
	Verify the signature of a ZIP file using a public key. More...

BA_API void	balua_installZIO (lua_State L, const char name, struct ZipReader *reader)
	Install a Zip I/O interface into the Lua environment. More...

Macro Definition Documentation

◆ BA_LUA_DECLARE_MUTEX

#define BA_LUA_DECLARE_MUTEX	(	name,
		L
	)	ThreadMutex* name = baluaENV_getmutex(L)

Declare a borrowed server mutex pointer from a BAS Lua binding state.

Parameters

name	Local variable to declare; no lock operation is performed.
L	Required Lua state whose binding environment supplies the mutex. Use balua_releasemutex(name) before blocking native work, then balua_setmutex(name) before accessing Lua again.

◆ balua_create

#define balua_create ( p ) _balua_create(p, BALUA_VERSION)

Create a BAS Lua VM.

Use this macro instead of calling _balua_create() directly so the runtime can verify the BAS library version.

Parameters

p	Required pointer to initialized BaLua_param. The structure is copied; referenced resources are borrowed. In a normal server build, set L to NULL and provide vmio. BA_ENABLE_SERVER=0 instead requires an existing L.

Returns: Initialized Lua state, or NULL for invalid parameters/version or initial allocation failure. Later VM initialization errors can invoke the fatal handler. Release a successful VM with balua_close().

◆ balua_getmutex

#define balua_getmutex ( L ) balua_getparam(L)->mutex

Get the SoDisp mutex associated with the Lua VM.

Parameters

L	Required BAS Lua state.

Returns: Borrowed mutex pointer, or NULL for a VM without a server mutex.

◆ balua_releasemutex

#define balua_releasemutex ( m ) if(m) ThreadMutex_release(m)

Release mutex m if it is not NULL.

Parameters

m	Borrowed ThreadMutex pointer, currently owned by this thread, or NULL. Reacquire before touching the Lua VM again.

◆ balua_setmutex

#define balua_setmutex ( m ) if(m) ThreadMutex_set(m)

Acquire mutex m, waiting if necessary.

Parameters

m	Borrowed ThreadMutex pointer, or NULL for no operation.

Typedef Documentation

◆ LHttpDir

typedef struct LHttpDir LHttpDir

LHttpDir is the HttpDir instance used by Lua bindings and can be used by advanced Lua bindings creating new HttpDir type Lua interfaces.

LHttpDir and Lua userdata memory layout:
+-----------+
| LHttpDir  |
+-----------+
| HttpDir   | <- Any type that inherits from HttpDir
+-----------+

Function Documentation

◆ _balua_create()

BA_API lua_State * _balua_create	(	const BaLua_param *	p,
		int	version
	)

Create a BAS Lua VM.

Use this macro instead of calling _balua_create() directly so the runtime can verify the BAS library version.

Parameters

p	Required pointer to initialized BaLua_param. The structure is copied; referenced resources are borrowed. In a normal server build, set L to NULL and provide vmio. BA_ENABLE_SERVER=0 instead requires an existing L.

Returns: Initialized Lua state, or NULL for invalid parameters/version or initial allocation failure. Later VM initialization errors can invoke the fatal handler. Release a successful VM with balua_close().

Parameters

version Compile-time BALUA_VERSION; use the macro to supply this.

◆ baCheckZipSignature()

BA_API int baCheckZipSignature	(	const U8 *	pubKey,
		U32	fileSize,
		struct CspReader *	reader
	)

Verify the signature of a ZIP file using a public key.

This function reads ZIP data through the supplied CspReader and verifies the archive signature with the provided public key.

Parameters

pubKey	Pointer to the public key used for signature verification.
fileSize	Size of the ZIP file in bytes.
reader	Pointer to the CspReader structure used for reading the ZIP file.

Returns: 0 when verified, -1 for invalid pointers/callback or fewer than 512 bytes, E_MALLOC for allocation failure, or E_TLS_CRYPTOERR for read/verification failure. No ownership transfers. pubKey uses SharkSSL ECC key encoding; this verifies the BAS signed-ZIP format, not arbitrary ZIP signatures.

◆ baLMalloc()

BA_API void * baLMalloc	(	lua_State *	L,
		size_t	size
	)

Allocate application memory, retrying after a full Lua GC on allocation failure.

Parameters

L	Required live Lua state, with its mutex held.
size	Requested number of bytes; use a positive size.

Returns: Caller-owned allocation to release with baFree, or NULL if both attempts fail. This helper does not raise an allocation error itself.

◆ baLRealloc()

BA_API void * baLRealloc	(	lua_State *	L,
		void *	p,
		size_t	size
	)

Resize application memory, retrying after a full Lua GC on allocation failure.

Parameters

L	Required live Lua state, with the dispatcher mutex held throughout. Keep the allocation's owner and Lua inputs reachable during collection, which can run finalizers.
p	Allocation compatible with baRealloc, or NULL for a new allocation.
size	Requested number of bytes. Zero delegates to baRealloc without collection or retry; its zero-size semantics apply.

Returns: Replacement allocation to release with baFree, or NULL on failure. For positive sizes, failure leaves p and its contents unchanged. This helper does not raise an allocation error itself.

◆ baLStrdup()

BA_API char * baLStrdup	(	lua_State *	L,
		const char *	str
	)

Duplicate a string using baLMalloc, including its full-GC retry on failure.

Parameters

L	Required live Lua state, with the dispatcher mutex held throughout.
str	NUL-terminated source, or NULL. Keep the source valid during collection, which can run finalizers; retain Lua-owned sources on the stack or through another strong reference until this function returns.

Returns: Caller-owned copy to release with baFree, or NULL for a NULL source or if both allocation attempts fail. This helper does not raise an allocation error itself.

◆ balua_close()

BA_API void balua_close ( lua_State * L )

Close the BAS Lua VM, run finalizers, and free its copied parameters.

Parameters

L	Required main state returned by balua_create; consumed by this call. Stop dispatching and terminate thread managers first. Hold the server mutex and retain borrowed server, timer, I/O, and tracker resources through cleanup. There is no return value and no subsequent Lua access is valid.

◆ balua_createiointf()

BA_API struct IoIntf ** balua_createiointf ( lua_State * L )

Push a Lua I/O userdata whose underlying interface is owned by Lua.

Parameters

L	Required BAS state with its mutex held.

Returns: Address of the userdata's initially NULL interface pointer. Assign a constructed baMalloc-allocated IoIntf. The Lua finalizer calls its destructor property and baFree. Keep the userdata reachable while using this pointer; do not separately destroy/free the assigned interface.

◆ balua_getmainthread()

BA_API lua_State * balua_getmainthread ( lua_State * L )

Get the main state without changing the stack.

Parameters

L	Required main state or coroutine belonging to the VM.

Returns: Borrowed main state; valid until VM shutdown.

◆ balua_getparam()

BA_API BaLua_param * balua_getparam ( lua_State * L )

Get the VM's stored parameter copy without changing the stack.

Parameters

L	Required initialized BAS state.

Returns: Borrowed parameters, valid until balua_close; do not free.

◆ balua_getuservalue()

BA_API void balua_getuservalue	(	lua_State *	L,
		int	index
	)

Pushes onto the stack the first user value associated with the full userdata at the given index.

This function is similar to lua_getiuservalue(), but creates a table at the first user value if it does not exist. Note index must be absolute i.e. not < 0. If the previous user value is non-nil, it is pushed unchanged.

Parameters

L	Required BAS state.
index	Positive absolute index of full userdata with a first user-value slot. Keep that slot nil or a table if a table is required by the caller.

◆ balua_installZIO()

BA_API void balua_installZIO	(	lua_State *	L,
		const char *	name,
		struct ZipReader *	reader
	)

Install a Zip I/O interface into the Lua environment.

This function registers a ZIP reader with the Lua environment, making it accessible via the provided name (the handle). It is typically used to enable the Lua function ba.mkio() to open embedded ZIP files.

Parameters

L	Pointer to the Lua state.
name	Name under which the ZIP reader will be installed in Lua and made available to ba.mkio(name)
reader	Borrowed initialized ZipReader, kept alive with its backing storage for every Lua I/O opened from this registration. Registration is stack-neutral and does not itself validate or copy the archive.

◆ balua_iointf()

BA_API IoIntf * balua_iointf	(	lua_State *	L,
		const char *	name,
		struct IoIntf *	newio
	)

Register an IoIntf instance with the Lua VM.

You may install any number of I/O interfaces, but each I/O interface must be registered with a unique name.

Parameters

L	the Lua state.
name	the name makes it possible to fetch the I/O using the Lua function ba.openio(name). Required NUL-terminated string; an empty string selects "vm". Do not pass NULL.
newio	the IoIntf instance, such as DiskIo, ZipIo, NetIo, or your own implementation. NULL looks up the current registration. A non-NULL interface is borrowed and replaces the named registration. Keep every registered interface alive while Lua objects may still use it.

Returns: Registered interface, or NULL when a lookup has no match. Stack is unchanged; this function neither destroys nor takes ownership of interfaces.

◆ balua_loadconfig()

BA_API int balua_loadconfig	(	lua_State *	L,
		struct IoIntf *	io,
		const char *	filename
	)

Load a Lua script and run the script at startup.

You may call this function multiple times during startup.

Parameters

L	the Lua state.
io	the I/O interface to use when loading script 'filename'.
filename	the path+name of the Lua script. The name defaults to .config if this parameter is NULL.

Returns: 0 on success, or a Lua load/call status with an error message on top. Success restores the original stack. The script receives its filename as one argument. A missing .config is an error, not silently ignored.

◆ balua_loadconfigExt()

BA_API int balua_loadconfigExt	(	lua_State *	L,
		struct IoIntf *	io,
		const char *	filename,
		int	nresults
	)

Load a Lua script and run the script at startup.

You may call this function multiple times during startup. This function is extends balua_loadconfig and enables you to get return values from the script.

Parameters

L	the Lua state.
io	the I/O interface to use when loading script 'filename'.
filename	the path+name of the Lua script. The name defaults to .config if this parameter is NULL.
nresults	Nonnegative number of results to leave on the stack, or LUA_MULTRET for all results. The script receives its filename as one argument.

Returns: 0 on success; a Lua load/call status on failure with an error message on top. With zero requested results, success restores the original stack.

◆ balua_loadfile()

BA_API int balua_loadfile	(	lua_State *	L,
		const char *	filename,
		struct IoIntf *	io,
		int	envix
	)

Compile a Lua source or bytecode file without executing it.

Parameters

L	Required BAS state with its mutex held.
filename	Required NUL-terminated I/O path; NULL returns a file error.
io	Borrowed I/O interface; NULL returns a file error.
envix	Absolute stack index of the environment to set as the first upvalue, or zero to leave the chunk environment unchanged.

Returns: 0 with a compiled function pushed; Lua load error status or LUA_ERRFILE with an error message pushed on failure. Returns -1 if the requested environment cannot be assigned; that path also leaves the chunk. The resource is closed before return; close errors are not reported.

◆ balua_ubjson()

BA_API void balua_ubjson ( lua_State * L )

Install the UBJSON Lua API.

Parameters

L	Required initialized BAS state with its mutex held. Returns no value.

◆ balua_usertracker_create()

BA_API int balua_usertracker_create	(	lua_State *	L,
		U32	noOfLoginTrackerNodes,
		U32	maxNumberOfLogins,
		BaTime	banTime
	)

Install Lua bindings for the default login tracker.

See one of the two following C code examples for how to use this function: MakoMain.c or xedge.c

Parameters

L	the state
noOfLoginTrackerNodes	tracker size
maxNumberOfLogins	how many login attempts before user (IP address) is banned
banTime	how long in seconds to ban an IP address

Returns: 0 when bindings were installed, -1 if a tracker already exists or the ba table was unavailable. Allocation failures use Lua/native handling. Use the main state during startup; the VM owns the installed tracker.

See also: LoginTracker LoginTrackerIntf

Detailed Description

Modules

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ BA_LUA_DECLARE_MUTEX

◆ balua_create

◆ balua_getmutex

◆ balua_releasemutex

◆ balua_setmutex

Typedef Documentation

◆ LHttpDir

Function Documentation

◆ _balua_create()

◆ baCheckZipSignature()

◆ baLMalloc()

◆ baLRealloc()

◆ baLStrdup()

◆ balua_close()

◆ balua_createiointf()

◆ balua_getmainthread()

◆ balua_getparam()

◆ balua_getuservalue()

◆ balua_installZIO()

◆ balua_iointf()

◆ balua_loadconfig()

◆ balua_loadconfigExt()

◆ balua_loadfile()

◆ balua_ubjson()

◆ balua_usertracker_create()