summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/sol2/docs/source/errors.rst
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/sol2/docs/source/errors.rst')
-rw-r--r--3rdparty/sol2/docs/source/errors.rst19
1 files changed, 17 insertions, 2 deletions
diff --git a/3rdparty/sol2/docs/source/errors.rst b/3rdparty/sol2/docs/source/errors.rst
index 5088c09e48e..c44ebe76988 100644
--- a/3rdparty/sol2/docs/source/errors.rst
+++ b/3rdparty/sol2/docs/source/errors.rst
@@ -3,7 +3,16 @@ errors
how to handle exceptions or other errors
----------------------------------------
-Here is some advice and some tricks to use when dealing with thrown exceptions, error conditions and the like in Sol.
+Here is some advice and some tricks for common errors about iteration, compile time / linker errors, and other pitfalls, especially when dealing with thrown exceptions, error conditions and the like in Sol.
+
+
+Linker Errors
+-------------
+
+There are lots of reasons for compiler linker errors. A common one is not knowing that you've compiled the Lua library as C++: when building with C++, it is important to note that every typical (static or dynamic) library expects the C calling convention to be used and that Sol includes the code using ``extern 'C'`` where applicable.
+
+However, when the target Lua library is compiled with C++, one must change the calling convention and name mangling scheme by getting rid of the ``extern 'C'`` block. This can be achieved by adding ``#define SOL_USING_CXX_LUA`` before including sol2, or by adding it to your compilation's command line.
+
Catch and CRASH!
----------------
@@ -34,8 +43,14 @@ Sometimes, some scripts load poorly. Even if you protect the function call, the
Raw Functions
-------------
-When you push a function into Lua using Sol using any methods and that function exactly matches the signature ``int( lua_State* );``, it will be treated as a *raw C function*. This means that the usual exception trampoline Sol wraps your other function calls in will not be present. You will be responsible for catching exceptions and handling them before they explode into the C API (and potentially destroy your code). Sol in all other cases adds an exception-handling trampoline that turns exceptions into Lua errors that can be caught by the above-mentioned protected functions and accessors.
+When you push a function into Lua using Sol using any methods and that function exactly matches the signature ``int( lua_State* );`` (and is a free function (e.g., not a member function pointer)), it will be treated as a *raw C function*. This means that the usual exception trampoline Sol wraps your other function calls in will not be present. You will be responsible for catching exceptions and handling them before they explode into the C API (and potentially destroy your code). Sol in all other cases adds an exception-handling trampoline that turns exceptions into Lua errors that can be caught by the above-mentioned protected functions and accessors.
.. warning::
Do NOT assume that building Lua as C++ will allow you to throw directly from a raw function. If an exception is raised and it bubbles into the Lua framework, even if you compile as C++, Lua does not recognize exceptions other than the ones that it uses with ``lua_error``. In other words, it will return some completely bogus result, potentially leave your Lua stack thrashed, and the rest of your VM *can* be in a semi-trashed state. Please avoid this!
+
+
+Iteration
+---------
+
+Tables may have other junk on them that makes iterating through their numeric part difficult when using a bland ``for-each`` loop, or when calling sol's ``for_each`` function. Use a numeric look to iterate through a table. Iteration does not iterate in any defined order also: see :ref:`this note in the table documentation for more explanation<iteration_note>`.