engine/3rdparty/sol2-3.3.0/documentation/source/tutorial/ownership.rst
Ownership is important when managing resources in C++. sol has many ownership semantics which are generally safe by default. Below are the rules.
You can take a reference to something that exists in Lua by pulling out a :doc:sol::reference<../api/reference> or a :doc:sol::object<../api/object>:
.. literalinclude:: ../../../examples/source/tutorials/object_lifetime.cpp :linenos: :caption: object_lifetime.cpp
All objects must be destroyed before the sol::state is destroyed, otherwise you will end up with dangling references to the Lua State and things will explode in horrible, terrible fashion.
This applies to more than just sol::object: all types derived from sol::reference and sol::object (:doc:sol::table<../api/table> :doc:sol::userdata<../api/userdata>, etc.) must be cleaned up before the state goes out of scope.
sol will not take ownership of raw pointers: raw pointers do not own anything. sol will not delete raw pointers, because they do not (and are not supposed to) own anything:
.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp :linenos: :caption: pointer_lifetime.cpp :name: pointer-lifetime-raw-ptr :lines: 1-11,14-22, 74-
Use/return a unique_ptr or shared_ptr instead or just return a value:
.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp :linenos: :caption: (smart pointers) pointer_lifetime.cpp :name: pointer-lifetime-smart-ptr :lines: 1-11,25-44, 74-
If you have something you know is going to last and you just want to give it to Lua as a reference, then it's fine too:
.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp :linenos: :caption: (static) pointer_lifetime.cpp :name: pointer-lifetime-static :lines: 1-11,46-49,74-
sol can detect nullptr, so if you happen to return it there won't be any dangling because a sol::lua_nil will be pushed. But if you know it's nil beforehand, please return std::nullptr_t or sol::lua_nil:
.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp :linenos: :caption: (nil/nullptr) pointer_lifetime.cpp :name: pointer-lifetime-nil :lines: 1-11,51-
:doc:Proxy<../api/proxy> and result types are ephermeal. They rely on the Lua stack and their constructors / destructors interact with the Lua stack. This means they are entirely unsafe to return from functions in C++, without very careful attention paid to how they are used that often requires relying on implementation-defined behaviors.
Please be careful when using (protected_)function_result, load_result (especially multiple load/function results in a single C++ function!) stack_reference, and similar stack-based things. If you want to return these things, consider