Auto-binding C++ functions for Lua

One of my C++ side-projects uses Lua for scripting.

I wanted to integrate a scripting language into my project, and Lua has a strong reputation as a language for games and also for being easy to embed. I wanted to learn how Lua bindings work and then created a system to simplify using Lua in this project.

With a bit of macros and template metaprogramming, exposing new functions to Lua can be done with minimal effort. This approach also supports bridging complicated types across the boundary as well as custom smart pointer types.

Overview

Lua is super powerful as an embedded scripting language. With not much effort you can hook up configuration for your program through or it, or with a little bit of management, you can create sandboxed VMs with only the necessary functions available, or create scripts which use Lua coroutines to allow scripts to pause and resume behavior. Overall, my experience using Lua has been overwhelmingly positive.

lua_State represents an individual Lua VM in your program, and you can use multiple at the same time. Each VM has its own state of execution and its own set of functions which are attached to it. The salient point is that the Lua C API lets you make C/C++ functions available for calling from Lua. When doing this, you need to pass parameters and return values across the boundary between the Lua VM and the native side. This data transfer happens via Lua's stack.

When binding functions to Lua, you need to be careful to push and pop off the appropriate values from that stack as arguments for the C/C++ function being called. This gets tedious and error-prone to use the correct functions to shovel data across and also keep track of the appropriate index of the associated data.

Binding with Macros

I wrote a little library for my project to bind a function to Lua which transfers the data across the Lua/C++ boundary in a type-safe and automatic way. It handles static functions, but also member functions and custom handle (non-pointer) types.

There's a little bit of duplication, but it hides a lot of manual handling of parameters.

A macro creates the appropriate wrapper function to call the desired function.

PS_LUA_BIND_MEMBER_FN(CollisionChannelMap, addChannel)
PS_LUA_BIND_MEMBER_FN(CollisionChannelMap, lookupChannel)
PS_LUA_BIND_MEMBER_FN(CollisionChannelMap, setSelfResponse)
PS_LUA_BIND_MEMBER_FN(CollisionChannelMap, setMutualResponse)

A little bit of glue code is needed to feed to Lua to describe the binding.

PS_LUA_DEFINE_LIBOPEN(Collision)
{
    PS_LUA_NEW_LIB(Collision)
        PS_LUA_MAP_LIB_FN(CollisionChannelMap, addChannel)
        PS_LUA_MAP_LIB_FN(CollisionChannelMap, lookupChannel)
        PS_LUA_MAP_LIB_FN(CollisionChannelMap, setSelfResponse)
        PS_LUA_MAP_LIB_FN(CollisionChannelMap, setMutualResponse)
    PS_LUA_END_LIB(Collision)

    //  Add some constants to the map.
    LuaPushTable constants(L, false, 2);
    constants.push("CollisionResponseIgnore", CollisionResponseIgnore);
    constants.push("CollisionResponseCollide", CollisionResponseCollide);
    return 1;
}

This gets associated with the appropriate lua_State using luaL_requiref to make it available for use within Lua.

And that's it.

This provides dot notation Type.function calls from Lua.

collisionChannelPlayer = Collision.addChannel(collisionChannelMap, "player")

There's other flavors to allow Object:function to automatically pass the original object type, but both of these things work roughly the same way under the hood.

PS_LUA_BIND_HANDLE(Actor)
PS_LUA_BIND_HANDLE_MEMBER_FN(Actor, getPosition)
PS_LUA_BIND_HANDLE_MEMBER_FN(Actor, setPosition)
PS_LUA_BIND_HANDLE_MEMBER_FN(Actor, getComponentByName)

PS_LUA_DEFINE_LIBOPEN(Actor)
{
    PS_LUA_NEW_METATABLE(Actor)
        PS_LUA_MAP_LIB_FN(Actor, getPositionXY)
        PS_LUA_MAP_LIB_FN(Actor, setPositionXY)
        PS_LUA_MAP_LIB_FN(Actor, getComponentByName)
        PS_LUA_MAP_LIB_FN(Actor, addComponentByName)
        PS_LUA_MAP_LIB_FN(Actor, getPosition)
        PS_LUA_MAP_LIB_FN(Actor, setPosition)
    PS_LUA_END_METATABLE(Actor, kMetatableActor)

    return 1;
}

Macros inside of macros

/// Binds a member function of a class to Lua.
#define PS_LUA_BIND_MEMBER_FN(Class, MemberFn)          \
    PS_LUA_DEFINE_LIB_STATIC_FN(Class, MemberFn)        \
    {                                                   \
        PROFILE_BINDING_CALL(Class::MemberFn);          \
        ps::AutoBind aparams(L, #Class "::" #MemberFn); \
        aparams.pushTarget<Class, Class*>();            \
        return aparams.call(&Class::MemberFn);          \
    }

CLion lets you expand macros inline. So let's unwrap what actually gets generated from this line:

PS_LUA_BIND_MEMBER_FN(CollisionChannelMap, addChannel)

After one substitution you see the internals.

PS_LUA_DEFINE_LIB_STATIC_FN(CollisionChannelMap, addChannel)
{
    PROFILE_BINDING_CALL(CollisionChannelMap::addChannel);
    ps::AutoBind aparams(L,
        "CollisionChannelMap"
        "::"
        "addChannel");
    aparams.pushTarget<CollisionChannelMap, CollisionChannelMap*>();
    return aparams.call(&CollisionChannelMap::addChannel);
}

The wrapping function name gets stitched together from PS_LUA_DEFINE_LIB_STATIC_FN after a couple expands. PS_LUA_FN_IDENTIFIER does some fancy stitching together a unique name for the call.

static Int PS_LUA_FN_IDENTIFIER(CollisionChannelMap, addChannel)(lua_State * L) noexcept
{
    PROFILE_BINDING_CALL(CollisionChannelMap::addChannel);
    ps::AutoBind aparams(L,
        "CollisionChannelMap"
        "::"
        "addChannel");
    aparams.pushTarget<CollisionChannelMap, CollisionChannelMap*>();
    return aparams.call(&CollisionChannelMap::addChannel);
}

This is the final result.

static Int lua_CollisionChannelMap_addChannel(lua_State* L) noexcept
{
    PROFILE_BINDING_CALL(CollisionChannelMap::addChannel);
    ps::AutoBind aparams(L,
        "CollisionChannelMap"
        "::"
        "addChannel");
    aparams.pushTarget<CollisionChannelMap, CollisionChannelMap*>();
    return aparams.call(&CollisionChannelMap::addChannel);
}

Other than the logic for profiling, there really isn't much here except some template magic from aparams.call().

Hold onto your hats, we're about to go metaprogramming

Template metaprogramming is very powerful, but can be difficult to write and furthermore, to read.

AutoBind is a class to do the work of automatically passing and returning parameters to functions.

This member function of AutoBind is the start of the fun:

// Constant member function call.
template <typename T, typename Result, typename... Args>
Int call(Result (T::*fn)(Args...))
{
    // Counting the object as a parameter will confuse users.
    checkNumArguments(lua_gettop(state_) - 1, sizeof...(Args));
    return callMemberFunction<Result (T::*)(Args...), Result, Args...>(fn);
}

Let's walk through this.

The template needs to match against the class T containing the function. That function is going to have a return type (Result), which is potentially void. It could also have more than one argument (typename... Args). We're passing not just a function pointer here, but a member function pointer, which is associated with a class (T::*fn). Put together that gives us the parameter received by the call: Result (T::*fn)(Args...).

There's also a version used for const member functions. It has the same internals but needed a separate definition since const and non-const member function pointers are treated differently by the typechecker. That version adds const to the end of the type here, so the parameter type would be Result (T::*fn)(Args...) const.

checkNumArguments here is debug code that ignores the top argument which is the object that this function is being called upon.

call returns the result of another template function callMemberFunction, where the meat of how this works actually comes together. We have to prime the function with appropriate types to get everything to resolve across all the platforms I build this on (MSVC on Windows, GCC on Linux, and Clang on Apple and Linux). Let's look at a stripped down version of that function without any error handling to see the main flow.

/// Call a member function assuming the light user data is a pointer to
/// an appropriate object type.
template <typename Fn, typename Result, typename... Args>
Int callMemberFunction(Fn fn)
{
    using ClassPointer = typename GetCallerType<Fn>::Pointer;
    using Params = typename std::tuple<ClassPointer, ParamStorage<Args>...>;

    Params params;
    ClassPointer target = (ClassPointer)lua_touserdata(state_, param_);

    std::get<0>(params) = target;
    ++param_;

    // Parse remaining parameters.
    if constexpr (sizeof...(Args) >= 1) {
        // Member functions have 1 extra argument due to the "this" pointer.
        gatherParams<Params, 1>(params, std::make_index_sequence<sizeof...(Args)> {});
    }

    if constexpr (std::is_void_v<Result>) {
        std::apply(fn, params);
        return 0;
    } else {
        return LuaTransfer<Result>::push(state_, std::forward<Result>(std::apply(fn, std::move(params))));
    }
}

There's a hidden parameter when calling member functions in C++, which is the target object. That's the only required parameter. I wrote some safety elements around this and parameters which I'll go into after we look at how parameters are automatically passed.

The important part of the setup here is the funneling of parameters from the Lua data stack into a C++-side std::tuple used to call the function. Eventually, we end up calling std::apply(fn, params) which calls our bound member function fn, with our accumulated parameters (params) which have been marshalled across the Lua/C++ boundary.

using ClassPointer = typename GetCallerType<Fn>::Pointer;
using Params = typename std::tuple<ClassPointer, ParamStorage<Args>...>;

ClassPointer target = (ClassPointer)lua_touserdata(state_, param_);
Params params;
std::get<0>(params) = target;

We use a recursive template call to pull out all the parameters themselves, provided any additional parameters exist.

    // Parse remaining parameters.
    if constexpr (sizeof...(Args) >= 1) {
        // Member functions have 1 extra argument due to the "this" pointer.
        gatherParams<Params, 1>(params, std::make_index_sequence<sizeof...(Args)> {});
    }

gatherParams expands at compile-time to generate code to loop through all the indexes and pull each parameter off the Lua data stack. Each iteration increases the index being assigned, and a constexpr unrolls another iteration until all parameters are handled.

Since the fold uses the appropriate type as given in the function parameter tuple, the appropriate LuaTransfer<> specialization is used to transfer the data between Lua and C++.

template <typename Params, size_t Offset, size_t... I>
void gatherParams(Params& params, std::index_sequence<I...>)
{
    ((std::get<I + Offset>(params) = //
            LuaTransfer<std::tuple_element_t<I + Offset, Params>>::pull(state_, param_++)),
        ... // Fold expression to do this for all arguments.
    );
}

This is what gets the element from the Lua stack using an appropriate conversion function and then stuffs it into the parameter tuple for the call. This critical element is the bridge between the data that Lua is providing for the call and the C++ code being executed.

Shoveling Data across the Boundary

LuaTransfer defines the transfer of data to Lua ("push") and from Lua ("pull"). We want to avoid excessive copying when calling our functions to push values to Lua, so there's some compile-time logic to pass large values to the push function by const reference. We might need to copy a large amount of data onto the stack, but that doesn't mean we need to copy even more when doing the call to push that data.

/// Some parameters are not suitable for storing locally as a parameter to pass
/// eventually to Lua.  An example would be const& and & values, since they'd
/// need to be referenced at initial storage time and might not be supported by
/// std::tuple for storage and update.
template <typename T>
using ParamStorage = std::remove_cvref_t<T>;

template <typename T>
struct LuaTransfer {
    /// Structs smaller than or equal to a 64-bit register should be able to be
    /// passed as a register rather than on the stack.
    inline static constexpr Int kPassByValueThresholdSize = 8;

    /// When pushing parameters to Lua, don't copy them if they are big.
    using BaseType = std::remove_cvref_t<T>;
    using PushType = std::conditional_t<std::is_arithmetic_v<T> || std::is_pointer_v<T> || std::is_enum_v<T> ||
                                            (std::is_trivially_copyable_v<BaseType> &&
                                                sizeof(BaseType) <= kPassByValueThresholdSize) ||
                                            (std::is_same_v<jgp::Handle<typename InnerType<BaseType>::Type>, BaseType>),
        ParamStorage<T>,
        const T&>;

    /// Pulling a value out of Lua from an index on its stack.
    static T pull(lua_State* L, Int paramIdx);

    /// Pushing a value onto the Lua stack.
    static Int push(lua_State* L, PushType t);
};

That template gets specialized for every type that needs to cross the boundary between Lua and C++. This allows usage of those types as both parameter and return types. This also permits efficient built-in Lua C functions for types if available, as well as allowing to change the semantics of how types work. A 2D vector could allow passing as a table with named X and Y coordinates like exampleFunction ({x = 10, y = 20}).

Here's an example for bool:

template <>
bool LuaTransfer<bool>::pull(lua_State* state, Int paramIdx)
{
    if (!lua_isboolean(state, paramIdx)) {
        LuaUtil::debugDump(state);
        JGP_LOG_ERROR(jgp::LogSysMain, "Expected boolean parameter in script.");
    }
    return (lua_toboolean(state, paramIdx) != 0);
}

template <>
Int LuaTransfer<bool>::push(lua_State* L, bool b)
{
    lua_pushboolean(L, b);
    return 1;
}

Composibility of `LuaTransfer<>`

Some types are composed of other C++ types, like an axis-aligned box with a min and max point. LuaTransfer<> implementations get reused by some helper types to pass these values within other types.

template <>
AABB2f LuaTransfer<AABB2f>::pull(lua_State* state, Int paramIdx)
{
    if (!lua_istable(state, paramIdx)) {
        LuaUtil::debugDump(state);
        JGP_LOG_ERROR(jgp::LogSysMain, "Expected a table for an AABB2f.");
    }

    LuaPullTable table(state, paramIdx);
    AABB2f aabb;
    table.pull("min", aabb.min);
    table.pull("max", aabb.max);
    return aabb;
}

template <>
Int LuaTransfer<AABB2f>::push(lua_State* L, const AABB2f& aabb)
{
    LuaPushTable table(L, true, 2);
    table.push("min", aabb.min);
    table.push("max", aabb.max);
    return 1;
}

If there's a result from the function, we can return it using appropriate specialized LuaTransfer::push function.

if constexpr (std::is_void_v<Result>) {
    std::apply(fn, params);
    return 0;
} else {
    return LuaTransfer<Result>::push(state_, std::forward<Result>(std::apply(fn, params)));
}