As noted in Section 5.5, lua_Objects 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 that 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,
whereas lua_pushref pushes the object on the stack.
If the object has been collected,
then 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.