As already noted, lua_Object
s are volatile.
If the C code needs to keep a lua_Object
outside block boundaries,
it must create a reference to the object.
The routines to manipulate references are the following:
int lua_ref (int lock);
lua_Object lua_getref (int ref);
void lua_pushref (int ref);
void lua_unref (int ref);
The function lua_ref
creates a reference
to the object which is on the top of the stack,
and returns this reference.
If lock
is true, the object is locked:
that means the object will not be garbage collected.
Notice that an unlocked reference may be garbage collected.
Whenever the referenced object is needed,
a call to lua_getref
returns a handle to it,
while lua_pushref
pushes the object on the stack.
If the object has been collected,
lua_getref
returns LUA_NOOBJECT
,
and lua_pushobject
issues an error.
When a reference is no longer needed, it can be freed with a call to lua_unref .