Lua Torch C API

Lua Torch C API

luaT provides an API to interface Lua and C in Torch packages. It defines a concept of classes to Lua for Torch, and provides a mechanism to easily handle these Lua classes from C.

It additionally provides few functions that luaL should have defined, and defines several functions similar to luaL ones for better type error printing when using luaT classes.

Memory functions

Classical memory allocation functions which generate a Lua error in case of problem.

void* luaT_alloc(lua_State *L, long size)

Allocates size bytes, and return a pointer on the allocated memory. A Lua error will be generated if running out of memory.

void* luaT_realloc(lua_State L, void ptr, long size)

Realloc ptr to size bytes. ptr must have been previously allocated with luaT_alloc or luaT_realloc, or the C malloc or realloc functions. A Lua error will be generated if running out of memory.

void luaT_free(lua_State L, void ptr)

Free memory allocated at address ptr. The memory must have been previously allocated with luaT_alloc or luaT_realloc, or the C malloc or realloc functions.

Class creation and basic handling

A luaT class is basically either a Lua table or userdata with an appropriate metatable. This appropriate metatable is created with luaT_newmetatable. Contrary to luaL userdata functions, luaT mechanism handles inheritance. If the class inherit from another class, then the metatable will itself have a metatable corresponding to the parent metatable: the metatables are cascaded according to the class inheritance. Multiple inheritance is not supported.

Operator overloading

The metatable of a luaT object contains Lua operators like __index, __newindex, __tostring, __add (etc…). These operators will respectively look for __index__, __newindex__, __tostring__, __add__ (etc…) in the metatable. If found, the corresponding function or value will be returned, else a Lua error will be raised.

If one wants to provide __index__ or __newindex__ in the metaclass, these operators must follow a particular scheme:

__index__ must either return a value and true or return false only. In the first case, it means __index__ was able to handle the given argument (for e.g., the type was correct). The second case means it was not able to do anything, so __index in the root metatable can then try to see if the metaclass contains the required value.

__newindex__ must either return true or false. As for __index__, true means it could handle the argument and false not. If not, the root metatable __newindex will then raise an error if the object was a userdata, or apply a rawset if the object was a Lua table.

Other metaclass operators like __tostring__, __add__, etc… do not have any particular constraint.

const char* luaT_newmetatable(lua_State L, const char tname, const char *parenttname, lua_CFunction constructor, lua_CFunction destructor, lua_CFunction factory)

This function creates a new metatable, which is the Lua way to define a new object class. As for luaL_newmetatable, the metatable is registered in the Lua registry table, with the key tname. In addition, tname is also registered in the Lua registry, with the metatable as key (the typename of a given object can be thus easily retrieved).

The class name tname must be of the form modulename.classname. The module name If not NULL, parenttname must be a valid typename corresponding to the parent class of the new class.

If not NULL, constructor, a function new will be added to the metatable, pointing to this given function. The constructor might also be called through modulename.classname(), which is an alias setup by luaT_metatable.

If not NULL, destructor will be called when garbage collecting the object.

If not NULL, factory must be a Lua C function creating an empty object instance of the class. This functions are used in Torch for serialization.

Note that classes can be partly defined in C and partly defined in Lua: once the metatable is created in C, it can be filled up with additional methods in Lua.

The return value is the value returned by luaT_typenameid.

int luaT_pushmetatable(lua_State L, const name tname)

Push the metatable with type name tname on the stack, it tname is a valid Torch class name (previously registered with luaT_newmetatable).

On success, returns 1. If tname is invalid, nothing is pushed and it returns 0.

const char* luaT_typenameid(lua_State L, const char tname)

If tname is a valid Torch class name, then returns a unique string (the contents will be the same than tname) pointing on the string registered in the Lua registry. This string is thus valid as long as Lua is running. The returned string shall not be freed.

If tname is an invalid class name, returns NULL.

const char* luaT_typename(lua_State *L, int ud)

Returns the typename of the object at index ud on the stack. If it is not a valid Torch object, returns NULL.

void luaT_pushudata(lua_State L, void udata, const char *tname)

Given a C structure udata, push a userdata object on the stack with metatable corresponding to tname. Obviously, tname must be a valid Torch name registered with luaT_newmetatable.

void luaT_toudata(lua_State L, int ud, const char *tname)

Returns a pointer to the original C structure previously pushed on the stack with luaT_pushudata, if the object at index ud is a valid Torch class name. Returns NULL otherwise.

int luaT_isudata(lua_State L, int ud, const char tname)

Returns 1 if the object at index ud on the stack is a valid Torch class name tname. Returns 0 otherwise.

Checking fields of a table

This functions check that the table at the given index ud on the Lua stack has a field named field, and that it is of the specified type. These function raises a Lua error on failure.

void luaT_getfieldcheckudata(lua_State L, int ud, const char field, const char tname)

Checks that the field named field of the table at index ud is a Torch class name tname. Returns the pointer of the C structure previously pushed on the stack with luaT_pushudata on success. The function raises a Lua error on failure.

void luaT_getfieldchecklightudata(lua_State L, int ud, const char *field)

Checks that the field named field of the table at index ud is a lightuserdata. Returns the lightuserdata pointer on success. The function raises a Lua error on failure.

int luaT_getfieldcheckint(lua_State L, int ud, const char field)

Checks that the field named field of the table at index ud is an int. Returns the int value pointer on success. The function raises a Lua error on failure.

const char* luaT_getfieldcheckstring(lua_State L, int ud, const char field)

Checks that the field named field of the table at index ud is a string. Returns a pointer to the string on success. The function raises a Lua error on failure.

int luaT_getfieldcheckboolean(lua_State L, int ud, const char field)

Checks that the field named field of the table at index ud is a boolean. On success, returns 1 if the boolean is true, 0 if it is false. The function raises a Lua error on failure.

void luaT_getfieldchecktable(lua_State L, int ud, const char field)

Checks that the field named field of the table at index ud is a table. On success, push the table on the stack. The function raises a Lua error on failure.

int luaT_typerror(lua_State L, int ud, const char tname)

Raises a luaL_argerror (and returns its value), claiming that the object at index ud on the stack is not of type tname. Note that this function does not check the type, it only raises an error.

int luaT_checkboolean(lua_State *L, int ud)

Checks that the value at index ud is a boolean. On success, returns 1 if the boolean is true, 0 if it is false. The function raises a Lua error on failure.

int luaT_optboolean(lua_State *L, int ud, int def)

Checks that the value at index ud is a boolean. On success, returns 1 if the boolean is true, 0 if it is false. If there is no value at index ud, returns def. In any other cases, raises an error.

void luaT_registeratname(lua_State L, const struct luaL_Reg methods, const char *name)

This function assume a table is on the stack. It creates a table field name in the table (if this field does not exist yet), and fill up methods in this table field.

const char luaT_classrootname(const char tname)

Assuming tname is of the form modulename.classname, returns classname. The returned value shall not be freed. It is a pointer inside tname string.

const char luaT_classmodulename(const char tname)

Assuming tname is of the form modulename.classname, returns modulename. The returned value shall not be freed. It is valid until the next call to luaT_classrootname.

void luaT_stackdump(lua_State *L)

This function print outs the state of the Lua stack. It is useful for debug purposes.