Learning Lua: 7 - userdata
1. Userdata basic
"There are eight basic types in Lua: nil, boolean, number, string, userdata, function, thread, and table.
The type() function gives the type name of any given value. " Ref[1]
"The userdata type allows arbitrary C data to be stored in Lua variables. It has no predefined operations in Lua, except
assignment and equality test. Userdata are used to represent new types created by an application program or alibrary
written in C " Ref[1] - 2.7 Userdata and Threads p18
"Lua compares tables and userdata by reference, that is, two such values are considered equal only if they are the very
same object. " Ref[1] - 3.2 Relational Operations p22
2. Userdata and Metatable
"Tables and userdata have individual metatables; values of other types share one single metatable for all values of
that type. " Ref[1] - 13 Metatables and Metamethods p127
"The usual method to distinguish one type of userdata from other userdata is to create a unique metatable for that type.
Everytime we create a userdata, we mark it with the corresponding metatable; everytime we get a userdata, we check
whether it has the right metatable. " Ref[1] - 29.2 Metatables p296
3. Lua C API for userdata
Lua C API 中提供的针对userdata的接口有:
| C API | 接口说明 |
| lua_isuserdata |
int lua_isuserdata (lua_State *L, int index); Returns 1 if the value at the given acceptable index is a userdata (either full or light), and 0 otherwise. 1 LUA_API void *lua_touserdata (lua_State *L, int idx) { 2 StkId o = index2adr(L, idx); 3 switch (ttype(o)) { 4 case LUA_TUSERDATA: return (rawuvalue(o) + 1); 5 case LUA_TLIGHTUSERDATA: return pvalue(o); 6 default: return NULL; 7 } 8 } |
| lua_touserdata |
void *lua_touserdata (lua_State *L, int index); If the value at the given acceptable index is a full userdata, returns its block address. If the value is a light userdata, returns its pointer. Otherwise, returns |
| lua_pushlightuserdata |
void lua_pushlightuserdata (lua_State *L, void *p); Pushes a light userdata onto the stack. Userdata represent C values in Lua. A light userdata represents a pointer. It is a value (like a number): you do not create it, it has no individual metatable, and it is not collected (as it was never created). A light userdata is equal to "any" light userdata with the same C address. |
| lua_newuserdata |
void *lua_newuserdata (lua_State *L, size_t size); This function allocates a new block of memory with the given size, pushes onto the stack a new full userdata with the block address, and returns this address. Userdata represent C values in Lua. A full userdata represents a block of memory. It is an object (like a table): you must create it, it can have its own metatable, and you can detect when it is being collected. A full userdata is only equal to itself (under raw equality). When Lua collects a full userdata with a is collected again then Lua frees its corresponding memory. |
| luaL_checkudata |
void *luaL_checkudata (lua_State *L, int narg, const char *tname); Checks whether the function argument |
4. full userdata and light userdata
"A light userdatum is a value that represents a C pointer (that is, a value). A light userdata is a value, not an object;
we do not create them " Ref[1] 29.5 Light Userdata p301
"Light userdata are not buffers, but single pointers. They have no metatables. Like numbers, light userdata are not
managed by the garbage collector. " Ref[1] 29.5 Light Userdata p302
"The real use of light userdata comes from equality. As a full userdata is an object, it is only equal to itself.
A light userdata, on the other hand, represents a C pointer value. As such, it is equal to any userdata that represents
the same pointer. Therefore, we can use light userdata to find C objects inside Lua. "
"Another typical scenario is the need to retrieve a full userdata given its C address. "
Ref[1] 29.5 Light Userdata p303
"We can not store a Lua table inside a userdatum(or inside any C structure), but Lua allows each userdata to
have a user value, which can be any Lua table, associated to it." Ref[1] 30.2 An XML Parser p311
other: thread function table
Reference
1. <<Programming in Lua>> 3rd Edition