Lua.LearningLua.7-userdata

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. LUA_API void *lua_touserdata (lua_State *L, int idx) { StkId o = index2adr(L, idx); switch (ttype(o)) { case LUA_TUSERDATA: return (rawuvalue(o) + 1); case LUA_TLIGHTUSERDATA: return pvalue(o); default: return NULL; } }
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 NULL.
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 gc metamethod, Lua calls the metamethod and marks the userdata as finalized. When this userdata 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 narg is a userdata of the type tname

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