exceptions

since somebody is going to ask about it…

Yes, you can turn off exceptions in sol with #define SOL_NO_EXCEPTIONS before including or by passing the command line argument that defines SOL_NO_EXCEPTIONS. We don’t recommend it unless you’re playing with a Lua distro that also doesn’t play nice with exceptions (like non-x64 versions of LuaJIT ).

If you turn this off, the default at_panic function state set for you will not throw (see sol::state’s automatic handlers for more details). Instead, the default Lua behavior of aborting will take place (and give you no chance of escape unless you implement your own at_panic function and decide to try longjmp out).

To make this not be the case, you can set a panic function directly with lua_atpanic( lua, my_panic_function ); or when you create the sol::state with sol::state lua(my_panic_function);. Here’s an example my_panic_function you can have that prints out its errors:

typical panic function

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>
#include <iostream>

inline void my_panic(sol::optional<std::string> maybe_msg) {
	std::cerr << "Lua is in a panic state and will now abort() "
	             "the application"
	          << std::endl;
	if (maybe_msg) {
		const std::string& msg = maybe_msg.value();
		std::cerr << "\terror message: " << msg << std::endl;
	}
	// When this function exits, Lua will exhibit default
	// behavior and abort()
}

int main(int, char*[]) {
	sol::state lua(sol::c_call<decltype(&my_panic), &my_panic>);
	// or, if you already have a lua_State* L
	// lua_atpanic( L, sol::c_call<decltype(&my_panic),
	// &my_panic> ); or, with state/state_view: sol::state_view
	// lua(L); lua.set_panic( sol::c_call<decltype(&my_panic),
	// &my_panic> );

	// uncomment the below to see
	// lua.script("boom_goes.the_dynamite");

	return 0;
}

Note that SOL_NO_EXCEPTIONS will also disable sol::protected_function’s ability to catch C++ errors you throw from C++ functions bound to Lua that you are calling through that API. So, only turn off exceptions in sol if you’re sure you’re never going to use exceptions ever. Of course, if you are ALREADY not using Exceptions, you don’t have to particularly worry about this and now you can use sol!

If there is a place where a throw statement is called or a try/catch is used and it is not hidden behind a #ifndef SOL_NO_EXCEPTIONS block, please file an issue at issue or submit your very own pull request so everyone can benefit!

various sol and lua handlers

Lua comes with two kind of built-in handlers that sol provides easy opt-ins for. One is the panic function, as demonstrated above. Another is the pcall error handler, used with sol::protected_function. It is any function that takes a single argument. The single argument is the error type being passed around: in Lua, this is a single string message:

regular error handling

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>

int main() {
	std::cout << "=== protected_functions ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	// A complicated function which can error out
	// We define both in terms of Lua code

	lua.script(R"(
			function handler (message)
				return "Handled this message: " .. message
			end

			function f (a)
				if a < 0 then
					error("negative number detected")
				end
				return a + 5
			end
		)");

	// Get a protected function out of Lua
	sol::protected_function f(lua["f"], lua["handler"]);

	sol::protected_function_result result = f(-500);
	if (result.valid()) {
		// Call succeeded
		int x = result;
		std::cout << "call succeeded, result is " << x
		          << std::endl;
	}
	else {
		// Call failed
		sol::error err = result;
		std::string what = err.what();
		std::cout << "call failed, sol::error::what() is "
		          << what << std::endl;
		// 'what' Should read
		// "Handled this message: negative number detected"
	}

	std::cout << std::endl;
}

The other handler is specific to sol2. If you open a sol::state, or open the default state handlers for your lua_State* (see sol::state’s automatic handlers for more details), there is a sol::exception_handler_function type. It allows you to register a function in the event that an exception happens that bubbles out of your functions. The function requires that you push 1 item onto the stack that will be used with a call to lua_error

exception handling

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>


#include <iostream>

int my_exception_handler(lua_State* L,
     sol::optional<const std::exception&> maybe_exception,
     sol::string_view description) {
	// L is the lua state, which you can wrap in a state_view if
	// necessary maybe_exception will contain exception, if it
	// exists description will either be the what() of the
	// exception or a description saying that we hit the
	// general-case catch(...)
	std::cout << "An exception occurred in a function, here's "
	             "what it says ";
	if (maybe_exception) {
		std::cout << "(straight from the exception): ";
		const std::exception& ex = *maybe_exception;
		std::cout << ex.what() << std::endl;
	}
	else {
		std::cout << "(from the description parameter): ";
		std::cout.write(description.data(),
		     static_cast<std::streamsize>(description.size()));
		std::cout << std::endl;
	}

	// you must push 1 element onto the stack to be
	// transported through as the error object in Lua
	// note that Lua -- and 99.5% of all Lua users and libraries
	// -- expects a string so we push a single string (in our
	// case, the description of the error)
	return sol::stack::push(L, description);
}

void will_throw() {
	throw std::runtime_error("oh no not an exception!!!");
}

int main() {
	std::cout << "=== exception_handler ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);
	lua.set_exception_handler(&my_exception_handler);

	lua.set_function("will_throw", &will_throw);

	sol::protected_function_result pfr = lua.safe_script(
	     "will_throw()", &sol::script_pass_on_error);

	SOL_ASSERT(!pfr.valid());

	sol::error err = pfr;
	std::cout << err.what() << std::endl;

	std::cout << std::endl;

	return 0;
}

LuaJIT and exceptions

It is important to note that a popular 5.1 distribution of Lua, LuaJIT, has some serious caveats regarding exceptions. LuaJIT’s exception promises are flaky at best on x64 (64-bit) platforms, and entirely terrible on non-x64 (32-bit, ARM, etc.) platforms. The trampolines we have in place for all functions bound through conventional means in sol will catch exceptions and turn them into Lua errors so that LuaJIT remainds unperturbed, but if you link up a C function directly yourself and throw, chances are you might have screwed the pooch.

Testing in this closed issue that it doesn’t play nice on 64-bit Linux in many cases either, especially when it hits an error internal to the interpreter (and does not go through sol). We do have tests, however, that compile for our continuous integration check-ins that check this functionality across several compilers and platforms to keep you protected and given hard, strong guarantees for what happens if you throw in a function bound by sol. If you stray outside the realm of sol’s protection, however… Good luck.

Lua and LuaJIT C++ Exception Full Interoperability

You can #define SOL_EXCEPTIONS_SAFE_PROPAGATION before including sol or define SOL_EXCEPTIONS_SAFE_PROPAGATION on the command line if you know your implmentation of Lua has proper unwinding semantics that can be thrown through the version of the Lua API you have built / are using.

This will prevent sol from catching (...) errors in platforms and compilers that have full C++ exception interoperability. This means that Lua errors can be caught with catch (...) in the C++ end of your code after it goes through Lua, and exceptions can pass through the Lua API and Stack safely.

Currently, the only known platform to do this is the listed “Full” platforms for LuaJIT and Lua compiled as C++. This define is turned on automatically for compiling Lua as C++ and SOL_USING_CXX_LUA (or SOL_USING_CXX_LUA_JIT) is defined.

Warning

SOL_EXCEPTIONS_SAFE_PROPAGATION is not defined automatically when sol detects LuaJIT. It is your job to define it if you know that your platform supports it!