1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
|
ownership
=========
Ownership is important when managing resources in C++. sol has many ownership semantics which are generally safe by default. Below are the rules.
object ownership
----------------
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.
pointer ownership
-----------------
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,14-22, 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-
ephermeal (proxy) objects
-------------------------
: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
|
