OOLua  2.0.1
C++ and Lua binding
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
OOLUA::Lua_ref< ID > Struct Template Reference

A typed wrapper for a Lua reference. More...

#include <oolua_ref.h>

Public Member Functions

 Lua_ref ()
 Initialises the instance so that a call to valid will return false.
 
 Lua_ref (lua_State *const vm, int const &ref)
 Sets the lua_State and reference for the instance. More...
 
 Lua_ref (lua_State *const vm)
 Sets the lua_State for the instance and initialises the instance so that a call to valid will return false. More...
 
 Lua_ref (Lua_ref const &rhs) OOLUA_DEFAULT
 Creates a copy of rhs. More...
 
 ~Lua_ref () OOLUA_DEFAULT
 Destructor which releases a valid reference, removing the value from the registry.
 
bool valid () const
 Returns true if both the Lua instance is not NULL and the registry reference is not invalid.
 
lua_Statestate () const
 Returns the lua_State associated with the Lua reference.
 
int const & ref () const
 Returns the integer Lua registry reference value.
 
void set_ref (lua_State *const vm, int const &ref) OOLUA_DEFAULT
 Sets the stored reference and state. More...
 
bool operator== (Lua_ref const &rhs) const
 Compares this instance reference with the right hand side operand using lua_rawequal. More...
 
Lua_refoperator= (Lua_ref const &rhs)
 Makes this instance a copy of rhs. More...
 
void swap (Lua_ref &rhs)
 Swaps the Lua instance and the registry reference with rhs. More...
 

Detailed Description

template<int ID>
struct OOLUA::Lua_ref< ID >

A typed wrapper for a Lua reference.

The Lua_ref templated class stores a reference using Lua's reference system luaL_ref and luaL_unref, along with a lua_State. The reason this class stores the lua_State is to make it difficult to use the reference with another universe. A reference from the same Lua universe, even if it is from a different lua_State, is valid to be used in the universe.

The class takes ownership of any reference passed either to the two argument constructor or the set_ref function. On going out of scope a valid reference is guaranteed to be released, you may also force a release by passing an instance to swap for which valid returns false.

There are two special values for the reference which Lua provides, both of which OOLua will treat as an invalid reference:

  • LUA_REFNIL luaL_ref return value to indicate it encountered a nil object at the location the ref was asked for
  • LUA_NOREF guaranteed to be different from any reference return by luaL_ref
    Template Parameters
    IDLua type as returned by lua_type
    Note
  • Universe: A call to luaL_newstate or lua_newstate creates a Lua universe and a universe is completely independent of any other universe. lua_newthread and coroutine.create, create a lua_State in an already existing universe.
    Term first heard in a Lua mailing list post by Mark Hamburg.

Constructor & Destructor Documentation

template<int ID>
OOLUA::Lua_ref< ID >::Lua_ref ( lua_State *const  vm,
int const &  ref 
)

Sets the lua_State and reference for the instance.

Note
This does not preform any validation on the parameters and it is perfectly acceptable to pass parameters such that a call to valid will return false.
Parameters
[in]vmlua_State for which the ref is coupled with.
[in]refRegistry reference or registry special value for this instance.
template<int ID>
OOLUA::Lua_ref< ID >::Lua_ref ( lua_State *const  vm)
explicit

Sets the lua_State for the instance and initialises the instance so that a call to valid will return false.

Parameters
[in]vmlua_State for which this instance is coupled with.
template<int ID>
OOLUA::Lua_ref< ID >::Lua_ref ( Lua_ref< ID > const &  rhs)

Creates a copy of rhs.

If rhs is valid then creates a new Lua reference to the value which rhs refers to, otherwise it initialises this instance so that a Lua_ref::valid call returns false.

Parameters
[in]rhsReference for which this instance will initialise its internal state from.

Member Function Documentation

template<int ID>
Lua_ref& OOLUA::Lua_ref< ID >::operator= ( Lua_ref< ID > const &  rhs)

Makes this instance a copy of rhs.

Parameters
[in]rhsThe instance to make a copy of
Note
Even self assignment makes a copy, yet it will refer to the same actual Lua instance. It doesn't seem correct for every assignment to pay for a branch just to keep the internal reference id the same.
template<int ID>
bool OOLUA::Lua_ref< ID >::operator== ( Lua_ref< ID > const &  rhs) const

Compares this instance reference with the right hand side operand using lua_rawequal.

Parameters
[in]rhsRight hand side operand for the operator.

An invalid reference compares equal with any other invalid reference regardless of the lua_State members. This operator can produce different results for Lua versions 5.1 and 5.2. In the latter pushing the same C function twice to the stack using lua_pushcclosure and then comparing them will return true, yet in 5.1 this will return false.

Returns
bool Result of the comparison.
template<int ID>
void OOLUA::Lua_ref< ID >::set_ref ( lua_State *const  vm,
int const &  ref 
)

Sets the stored reference and state.

Releases any currently stored reference and takes ownership of the passed reference.

Parameters
[in]vmlua_State to associated the reference with.
[in]refRegistry reference id for which the instance takes ownership of.
template<int ID>
void OOLUA::Lua_ref< ID >::swap ( Lua_ref< ID > &  rhs)

Swaps the Lua instance and the registry reference with rhs.

Swaps the lua_State and reference with rhs, this is a simple swap and does not call luaL_ref therefore it will not create any new references.

Parameters
[in,out]rhsReference which will re-initialise this instance's state and which will receive the internal state of this instance as it was before the swap.

The documentation for this struct was generated from the following file: