summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/sol2/docs/source/tutorial/ownership.rst
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/sol2/docs/source/tutorial/ownership.rst')
-rw-r--r--3rdparty/sol2/docs/source/tutorial/ownership.rst94
1 files changed, 94 insertions, 0 deletions
diff --git a/3rdparty/sol2/docs/source/tutorial/ownership.rst b/3rdparty/sol2/docs/source/tutorial/ownership.rst
new file mode 100644
index 00000000000..96eb350da78
--- /dev/null
+++ b/3rdparty/sol2/docs/source/tutorial/ownership.rst
@@ -0,0 +1,94 @@
+ownership
+=========
+
+Sol will not take ownership of raw pointers: raw pointers do not own anything.
+
+.. code-block:: cpp
+
+ struct my_type {
+ void stuff () {}
+ };
+
+ sol::state lua;
+
+ // AAAHHH BAD
+ // dangling pointer!
+ lua["my_func"] = []() -> my_type* {
+ return new my_type();
+ };
+
+ // AAAHHH!
+ lua.set("something", new my_type());
+
+ // AAAAAAHHH!!!
+ lua["something_else"] = new my_type();
+
+Use/return a ``unique_ptr`` or ``shared_ptr`` instead or just return a value:
+
+.. code-block:: cpp
+
+ // :ok:
+ lua["my_func"] = []() -> std::unique_ptr<my_type> {
+ return std::make_unique<my_type>();
+ };
+
+ // :ok:
+ lua["my_func"] = []() -> std::shared_ptr<my_type> {
+ return std::make_shared<my_type>();
+ };
+
+ // :ok:
+ lua["my_func"] = []() -> my_type {
+ return my_type();
+ };
+
+ // :ok:
+ lua.set("something", std::unique_ptr<my_type>(new my_type()));
+
+ std::shared_ptr<my_type> my_shared = std::make_shared<my_type>();
+ // :ok:
+ lua.set("something_else", my_shared);
+
+ auto my_unique = std::make_unique<my_type>();
+ lua["other_thing"] = std::move(my_unique);
+
+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:
+
+.. code-block:: cpp
+
+ // :ok:
+ lua["my_func"] = []() -> my_type* {
+ static my_type mt;
+ return &mt;
+ };
+
+
+Sol can detect ``nullptr``, so if you happen to return it there won't be any dangling because a ``sol::nil`` will be pushed.
+
+.. code-block:: cpp
+
+ struct my_type {
+ void stuff () {}
+ };
+
+ sol::state lua;
+
+ // BUT THIS IS STILL BAD DON'T DO IT AAAHHH BAD
+ // return a unique_ptr still or something!
+ lua["my_func"] = []() -> my_type* {
+ return nullptr;
+ };
+
+ lua["my_func_2"] = [] () -> std::unique_ptr<my_type> {
+ // default-constructs as a nullptr,
+ // gets pushed as nil to Lua
+ return std::unique_ptr<my_type>();
+ // same happens for std::shared_ptr
+ }
+
+ // Acceptable, it will set 'something' to nil
+ // (and delete it on next GC if there's no more references)
+ lua.set("something", nullptr);
+
+ // Also fine
+ lua["something_else"] = nullptr;