Next: 6 Predefined Functions and Up: 5 The Application Program Previous: 5.5 C Functions

5.6 References to Lua Objects

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 .


Next: 6 Predefined Functions and Up: 5 The Application Program Previous: 5.5 C Functions