LuaCpp

For scenarios requiring frequent Lua script execution, use state pooling to avoid the overhead of repeated memory allocation and library loading. RunPooled() automatically acquires a state from the pool and returns it when finished.

Predefined Pool Colors

Custom Pools

You can define your own pool configuration using PoolConfig:

PoolConfig config;
config.libraries = {"base", "math"};
config.maxSize = 3;
ctx.createPool("math_only", config);
ctx.RunPooled("calculation", "math_only");

#include <LuaCpp.hpp>
#include <iostream>

using namespace LuaCpp;

int main(int argc, char **argv) {
	LuaContext ctx;

	// Compile a script
	ctx.CompileString("hello", "print('Hello from pooled state!')");

	// Execute using a pooled state
	try {
		ctx.RunPooled("hello");
	}
	catch (std::runtime_error& e) {
		std::cout << e.what() << '\n';
	}
}

Lua State Pooling is an opt-in system designed to reduce the overhead of creating and destroying lua_State instances. Instead of the default behavior where every execution creates a new state, you can use "colored pools" to reuse states that share the same configuration (libraries, globals, and hooks).

Key Concepts

• Pool Color: A string identifier representing a specific configuration. Different colors allow you to have different pools (e.g., a sandboxed pool with limited libraries and a default pool with all standard libraries).
• State Reuse: When a state is released back to a pool, it is reset (clearing the stack, resetting hooks, and restoring globals) before being made available for the next request.
• Thread Safety: Pooling is not thread-safe by default. You must explicitly enable it via the PoolManager to avoid synchronization issues when multiple threads acquire/release states.

Predefined Colors

To make existing C++ objects behave like native Lua types without moving their data into the Lua engine, inherit from LuaMetaObject and implement the following three methods:

• bool Exists(const std::string &name)
• std::shared_ptr<LuaType> getValue(std::string &key)
• void setValue(std::string &key, std::shared_ptr<LuaType> val)

This allows the Lua engine to interact with the object directly via these interface methods.

class MetaMap : public LuaMetaObject {
	public:
		std::map<std::string, std::shared_ptr<LuaType>> values;
		MetaMap() : values() {}
		
		bool inline Exists(const std::string &name) {
			return !(values.find( name ) == values.end());
		}

		std::shared_ptr<LuaType> getValue(std::string &key) {
			if (Exists(key)) {
				return values[key];
			}
			return std::make_shared<LuaTNil>();
		}

		void setValue(std::string &key, std::shared_ptr<LuaType> val) {
			values[key] = val;
		}
};

State pooling is a performance optimization that reuses lua_State instances across multiple script executions. Instead of allocating memory and loading libraries for every execution, states are borrowed from a pool and returned after use. This is particularly beneficial for high-frequency script execution or when running the same script repeatedly, as it amortizes memory allocation and library loading costs.

When to use pooling

• High-frequency script execution: Use pooling.
• Repeated script execution: Use pooling.
• Multi-threaded environments: Use pooling with thread safety enabled.
• One-off scripts: Regular Run() is sufficient.
• Different library requirements: Use different colored pools.

#include <LuaCpp.hpp>

using namespace LuaCpp;

int main() {
    LuaContext ctx;
    
    // Compile a script
    ctx.CompileString("hello", "print('Hello from pooled state!')");
    
    // Execute using a pooled state
    ctx.RunPooled("hello");
    
    // The state is automatically returned to the pool
    return 0;
}

The LuaContext class is the primary high-level abstraction for interacting with the Lua engine. It allows you to execute Lua code from strings or files.

To optimize performance, LuaCpp compiles and stores code in an internal registry for reuse. However, CompileStringAndRun() and CompileFileAndRun() will always recompile the provided code under the name default.

Thread Safety Warning: Lua is not thread-safe, and consequently, LuaContext instances are not thread-safe. In multithreaded environments, you should create a separate LuaContext instance for each thread.

#include <LuaCpp.hpp>
#include <iostream>

using namespace LuaCpp;
using namespace LuaCpp::Registry;
using namespace LuaCpp::Engine;

int main(int argc, char **argv) {
	LuaContext lua;

	// The simplest way to start
	try {
		lua.CompileStringAndRun("print('The fastest way to start using lua in a project')");
	}
	catch (std::runtime_error& e) {
		std::cout << e.what() << '\n';
	}
}