diff --git a/docs/source/api/function.rst b/docs/source/api/function.rst index 93adedab..1056bd2f 100644 --- a/docs/source/api/function.rst +++ b/docs/source/api/function.rst @@ -82,13 +82,17 @@ This makes it much easier to work with multiple return values. Using ``std::tie` Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types, ...)`` syntax. Function assumes there are no runtime errors, and thusly will call the ``atpanic`` function if an error does occur. + +.. _function-argument-handling: + +functions and argument passing +------------------------------ + .. note:: All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state` or :doc:`sol::table`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user. -.. _function-argument-handling: - .. note:: This also means that you should pass and receive arguments in certain ways to maximize efficiency. For example, ``sol::table``, ``sol::object``, ``sol::userdata`` and friends are fairly cheap to copy, and should simply by taken as values. This includes primitive types like ``int`` and ``double``. However, C++ types -- if you do not want copies -- should be taken as ``const type&`` or ``type&``, to save on copies if it's important. Note that taking references from Lua also means you can modify the data inside of Lua directly, so be careful. Lua by default deals with things mostly by reference (save for primitive types). diff --git a/docs/source/errors.rst b/docs/source/errors.rst index 896fa3b7..6df78c99 100644 --- a/docs/source/errors.rst +++ b/docs/source/errors.rst @@ -10,7 +10,7 @@ Catch and CRASH! By default, Sol will add a ``default_at_panic`` handler. If exceptions are not turned off, this handler will throw to allow the user a chance to recover. However, in almost all cases, when Lua calls ``lua_atpanic`` and hits this function, it means that something *irreversibly wrong* occured in your code or the Lua code and the VM is in an unpredictable or dead state. Catching an error thrown from the default handler and then proceeding as if things are cleaned up or okay is NOT the best idea. Unexpected bugs in optimized and release mode builds can result, among other serious issues. -It is preferred if you catch an error that you log what happened, terminate the Lua VM as soon as possible, and then crash if your application cannot handle spinning up a new Lua state. Catching can be done, but you should understand the risks of what you're doing when you do it. +It is preferred if you catch an error that you log what happened, terminate the Lua VM as soon as possible, and then crash if your application cannot handle spinning up a new Lua state. Catching can be done, but you should understand the risks of what you're doing when you do it. For more information about catching exceptions, the potentials, not turning off exceptions and other tricks and caveats, read about :doc:`exceptions in Sol here`. Lua is a C API first and foremost: exceptions bubbling out of it is essentially last-ditch, terminal behavior that the VM does not expect. You can see an example of handling a panic on the exceptions page :ref:`here`. diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst index 745a71d2..955f3e7f 100644 --- a/docs/source/exceptions.rst +++ b/docs/source/exceptions.rst @@ -51,12 +51,17 @@ Testing in `this closed issue`_ that it doesn't play nice on 64-bit Linux in man .. _LuaJIT C++ Exception Full Interoperability -LuaJIT C++ Exception Full Interoperability ------------------------------------------- +Lua and LuaJIT C++ Exception Full Interoperability +-------------------------------------------------- -If you are using a platform and compiler that has full c++ exception interoperability (http://luajit.org/extensions.html#exceptions), define ``SOL_LUAJIT_FULL_INTEROPERABILITY``. This will prevent sol from catching (...) errors - in platforms & compilers than have full c++ exception interoperability Lua errors can be caught with catch (...) in C++ - in these cases sol inaccurately prevents Lua errors from being propagated correctly. +You can ``#define SOL_EXCEPTIONS_SAFE_PROPOGATION`` before including Sol or define ``SOL_EXCEPTIONS_SAFE_PROPOGATION`` 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 +.. _platforms for LuaJIT: http://luajit.org/extensions.html#exceptions .. _this closed issue: https://github.com/ThePhD/sol2/issues/28 diff --git a/single/sol/sol.hpp b/single/sol/sol.hpp index 2506c18e..fa5cae33 100644 --- a/single/sol/sol.hpp +++ b/single/sol/sol.hpp @@ -20,8 +20,8 @@ // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. // This file was generated with a script. -// Generated 2016-11-13 06:01:48.356322 UTC -// This header was generated with sol v2.15.0 (revision 951b821) +// Generated 2016-11-13 08:48:07.077032 UTC +// This header was generated with sol v2.15.0 (revision 08a6585) // https://github.com/ThePhD/sol2 #ifndef SOL_SINGLE_INCLUDE_HPP @@ -3000,7 +3000,7 @@ namespace sol { catch (const std::exception& e) { lua_pushstring(L, e.what()); } -#ifndef SOL_LUAJIT_FULL_INTEROPERABILITY +#if !defined(SOL_EXCEPTIONS_SAFE_PROPOGATION) catch (...) { lua_pushstring(L, "caught (...) exception"); } @@ -3019,7 +3019,7 @@ namespace sol { catch (const std::exception& e) { lua_pushstring(L, e.what()); } -#ifndef SOL_LUAJIT_FULL_INTEROPERABILITY +#if !defined(SOL_EXCEPTIONS_SAFE_PROPOGATION) catch (...) { lua_pushstring(L, "caught (...) exception"); } diff --git a/sol/types.hpp b/sol/types.hpp index 789e177a..9b36e773 100644 --- a/sol/types.hpp +++ b/sol/types.hpp @@ -57,7 +57,7 @@ namespace sol { catch (const std::exception& e) { lua_pushstring(L, e.what()); } -#ifndef SOL_LUAJIT_FULL_INTEROPERABILITY +#if !defined(SOL_EXCEPTIONS_SAFE_PROPOGATION) catch (...) { lua_pushstring(L, "caught (...) exception"); } @@ -76,7 +76,7 @@ namespace sol { catch (const std::exception& e) { lua_pushstring(L, e.what()); } -#ifndef SOL_LUAJIT_FULL_INTEROPERABILITY +#if !defined(SOL_EXCEPTIONS_SAFE_PROPOGATION) catch (...) { lua_pushstring(L, "caught (...) exception"); }