Lua Define Function
C++ Map Of Lua Functions Tutorial

A template class for binding C++ to Lua

by Lenny Palozzi

Using user defined types (“usertype”s, or just “udt”s) is simple with sol. If you don’t call any member variables or functions, then you don’t even have to ‘register’ the usertype at all: just pass it through. But if you want variables and functions on your usertype inside of Lua, you need to register it. Do NOT save the return type of a unsafefunctionresult (functionresult when safety configurations are not turned on) with auto, as in auto numwoof = woof(20);, and do NOT store it anywhere.Unlike its counterpart protectedfunctionresult, functionresult is NOT safe to store as it assumes that its return types are still at the top of the stack and when its destructor is called will.

Abstract

This note explains a method of binding C++ classes to Lua. Lua does not support this directly, but it does provide a low level C API and extension mechanisms that makes it possible. The method I describe makes use of Lua's C API, C++ templates, and Lua's extension mechanisms to build a small and simple, yet effective static template class that provides a class registration service. The method imposes a few restriction on your classes, namely, only class member functions with the signature int(T::*)(lua_State*) can be registered. But as I'll show, this restriction can be overcome. The end result is a clean interface to register classes, and familiar Lua table semantics of classes in Lua. The solution explained here is based on a template class that I wrote calledLuna.

The problem

Lua's API is not designed to register C++ classes to Lua, only C functions that have the signature int()(lua_State*), that is, a function that takes an lua_State pointer as an argument and returns an integer. Actually, that is the only C data type that Lua supports in registering. To register any other type you have to use the extension mechanisms that Lua provides, tag methods, closures, etc. In building a solution that allows us to register C++ classes to Lua, we must make use of those extension mechanisms.

The solution

There are four components that make the solution, class registration, object instantiation, member function calling, and garbage collection.

Class registration is accomplished by registering a table constructor function with the name of the class. A table constructor function is a static method of the template class that returns a table object.

Note: Static class member functions are compatible with C functions, assuming their signatures are the same, thus we can register them in Lua. The code snippets below are member functions of a template class, 'T' is the class being bound.Object instantiation is accomplished by passing any arguments the user passed to the table constructor function to the constructor of the C++ object, creating a table that represents the object, registering any member functions of the class to that table, and finally returning the table to Lua. The object pointer is stored as a userdata in the table at index 0. The index into the member function map is stored as a closure value for each function. More on the member function map later.Unlike C functions, C++ member functions require an object of the class for the function to be called. Member function calling is accomplished by a function that 'thunks' the calls by acquiring the object pointer and member function pointer and making the actual call. The member function pointer is indexed from the member function map by the closure value, the object pointer from the table at index 0. Note that all class functions in Lua are registered with this function.Garbage collection is accomplished by setting a garbage collection tag method for the userdata in the table. When the garbage collector is run the 'gc' tag method will be called which simply deletes the object. The 'gc' tag method is registered during class registration with a new tag. At object instantiation above, the userdata is tagged with the tag value.With that in mind, there are a few requirements that a class must comply with as you may have noticed:

it must have a public constructor that takes a lua_State*
registered member functions must have the signature int(T::*)(lua_State*)
it must have a public static const char[] member called className
it must have a public static const Luna<T>::RegType[] member called Register

Note: These requirements are of the design choice I made, you may decide on a different interface; with only a few adjustments to the code.

Luna<T>::RegType is a function map. name is the name of the function that the member function mfunc will be registered as.Here's an example of how to register a C++ class to Lua. A call to Luna<T>::Register() will register the class; the only public interface of the template class. To use the class in Lua you create an instance of it by calling its table constructor function.The table of an Account instance looks like this:

Explanation

Some may not like the use of C++ templates, but their use here fits in well. They offer a quick tight solution to what initially seemed a complex problem. As a result of using templates the class is very type safe; for example its impossible to mix member functions of different classes in the member function map, the compiler will complain. Additionally, the static design of the template class makes it easy to use, there are no template instantiated objects to cleanup when you're done.

The thunk mechanism is the core of the class, as it 'thunks' the call. It does so by taking the object pointer from the table the function call is associated to, and indexing the member function map for the member function pointer. (Lua table function calls of table:function() is syntactic sugar for table.function(table). When the call is made Lua first pushes the table on the stack, then any arguments). The member function index is a closure value, pushed onto the stack last (after any arguments). Initially I had the object pointer as a closure which meant having 2 closure values, a pointer to object(a void*) and the member function index(an int) for every class instantiated for every function; which seemed rather costly but provided quick access to the object pointer. As well, a userdata object in the table for garbage collection purposes was required. In the end I opted to index the table for the object pointer and save on resources, as a result increasing the function call overhead; a table lookup for the object pointer.

All facts considered, the implementation makes use of only a few of Lua's available extension mechanisms, closures for holding the index to the member function, the 'gc' tag method for garbage collection, and function registration for table constructor and member function calls.

Why allow only member functions with the signature int(T::*)(lua_State*) to be registered? This allows your member functions to interact directly with Lua; retrieving arguments and returning values to Lua, calling any Lua API function, etc. Moreover, it provides an identical interface that C functions have when registered to Lua, making it easier for those wishing to use C++.

Weaknesses

This template class solution only binds member functions with a specific signature as described earlier. Thus if you already have classes written, or are intending to use the class in both Lua and C++ environments, this may not be the best solution for you. In the abstract I mentioned that I'd explain that this isn't really a problem. Using the proxy pattern, we encapsulate the real class and delegate any calls made to it to the target object. The member functions of the proxy class coerce the arguments and return values to and from Lua, and delegate the calls to the target object. You would register the proxy class with Lua, not the real class. Additionally, you may use inheritance as well where the proxy class inherits from the base class and delegates the function calls up to the base class, but with one caveat, the base class must have a default constructor; you cannot get the constructor arguments from Lua to the base class in the proxy's constructor initializer list. The proxy pattern solves our problem, we now can use the class in both C++ and Lua, but in doing so requires us to write proxy classes and maintain them.

Objects are simply new'ed when created, more control as to how an object is created should be given to the user. For example, the user may wish to register a singleton class.

C++ Map Of Lua Functions