summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/sol2/docs/source/exceptions.rst
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/sol2/docs/source/exceptions.rst')
-rw-r--r--3rdparty/sol2/docs/source/exceptions.rst36
1 files changed, 25 insertions, 11 deletions
diff --git a/3rdparty/sol2/docs/source/exceptions.rst b/3rdparty/sol2/docs/source/exceptions.rst
index 13be8b9a667..0e6584a20ef 100644
--- a/3rdparty/sol2/docs/source/exceptions.rst
+++ b/3rdparty/sol2/docs/source/exceptions.rst
@@ -11,23 +11,27 @@ To make this not be the case, you can set a panic function directly with ``lua_a
.. code-block:: cpp
:caption: regular panic function
+ :name: typical-panic-function
#include <sol.hpp>
#include <iostream>
- int my_panic_function( lua_State* L ) {
- // error message is at the top of the stack
- const char* message = lua_tostring(L, -1);
- // message can be null, so don't crash
- // us with nullptr-constructed-string if it is
- std::string err = message ? message : "An unexpected error occurred and forced the lua state to call atpanic";
- // Weee
- std::cerr << err << std::endl;
+ 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 () {
- sol::state lua(my_panic_function);
+ 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> );
}
@@ -41,11 +45,21 @@ If there is a place where a throw statement is called or a try/catch is used and
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.) platorms. 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.
+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 not turned on automatically, even if Sol detects LuaJIT: *it is your job to define it if you know that your platform supports it*!
+
.. _issue: https://github.com/ThePhD/sol2/issues/
.. _at_panic: http://www.Lua.org/manual/5.3/manual.html#4.6
.. _caveats regarding exceptions: http://luajit.org/extensions.html#exceptions
-.. _this closed issue: https://github.com/ThePhD/sol2/issues/28 \ No newline at end of file
+.. _platforms for LuaJIT: http://luajit.org/extensions.html#exceptions
+.. _this closed issue: https://github.com/ThePhD/sol2/issues/28