Lua has automatic memory management, and garbage collection. Because of that, a lua_Object has a limited scope, and is only valid inside the block where it was created. A C function called from Lua is a block, and its parameters are valid only until its end. A good programming practice is to convert Lua objects to C values as soon as they are available, and never to store lua_Objects in C global variables.
When C code calls Lua repeatedly, as in a loop,
objects returned by these calls accumulate,
and may create a memory problem.
To avoid this,
nested blocks can be defined with the functions:
void lua_beginblock (void);
void lua_endblock (void);
After the end of the block,
all lua_Object's created inside it are released.
To check the type of a lua_Object,
the following function is available:
int lua_type (lua_Object object);
plus the following macros:
int lua_isnil (lua_Object object);
int lua_isnumber (lua_Object object);
int lua_isstring (lua_Object object);
int lua_istable (lua_Object object);
int lua_iscfunction (lua_Object object);
int lua_isuserdata (lua_Object object);
All macros return 1 if the object has the given type,
and 0 otherwise.
The function lua_type can be used to distinguish between different kinds of user data; see below.
To translate a value from type lua_Object to a specific C type,
the programmer can use:
double lua_getnumber (lua_Object object);
char *lua_getstring (lua_Object object);
lua_CFunction lua_getcfunction (lua_Object object);
void *lua_getuserdata (lua_Object object);
lua_getnumber converts a lua_Object to a float.
This lua_Object must be a number or a string convertible to number
(see Section 4.2); otherwise, the function returns 0.
lua_getstring converts a lua_Object to a string (char *). This lua_Object must be a string or a number; otherwise, the function returns 0 (the null pointer). This function does not create a new string, but returns a pointer to a string inside the Lua environment. Because Lua has garbage collection, there is no guarantee that such pointer will be valid after the block ends.
lua_getcfunction converts a lua_Object to a C function. This lua_Object must have type CFunction; otherwise, the function returns 0 (the null pointer). The type lua_CFunction is explained in Section 5.5.
lua_getuserdata converts a lua_Object to void*. This lua_Object must have type userdata; otherwise, the function returns 0 (the null pointer).
The reverse process, that is, passing a specific C value to Lua,
is done by using the following functions:
void lua_pushnumber (double n);
void lua_pushstring (char *s);
void lua_pushliteral (char *s);
void lua_pushcfunction (lua_CFunction f);
void lua_pushusertag (void *u, int tag);
plus the macro:
void lua_pushuserdata (void *u);
All of them receive a C value,
convert it to a correspondent lua_Object,
and leave the result on the top of the Lua stack,
where it can be assigned to a Lua variable,
passed as paramenter to a Lua function, etc (see below).
lua_pushliteral is like lua_pushstring,
but also puts the string in the Lua literal table.
This avoids the string to be garbage collected,
and therefore has a better overall performance.
As a rule, when the string to be pushed is a literal,
lua_pushliteral should be used.
User data can have different tags, whose semantics are defined by the host program. Any positive integer can be used to tag a user data. When a user data is retrieved, the function lua_type can be used to get its tag.
To complete the set,
the value nil or a lua_Object can also be pushed onto the stack,
with:
void lua_pushnil (void);
void lua_pushobject (lua_Object object);