diff options
author | 2017-02-05 16:01:50 +0100 | |
---|---|---|
committer | 2017-02-05 16:06:06 +0100 | |
commit | ac096aa2a0921efde96b76252dffb119dcf27efc (patch) | |
tree | 2ad9a28a7f6babce8cfcbf5995e3e055ff13ff60 /3rdparty/sol2/docs/source/api | |
parent | 29df715138452ee18ba19ec4b07e18c4b3185de7 (diff) |
Update sol2 (nw)
Diffstat (limited to '3rdparty/sol2/docs/source/api')
-rw-r--r-- | 3rdparty/sol2/docs/source/api/api-top.rst | 1 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/as_args.rst | 50 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/reference.rst | 5 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/resolve.rst | 4 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/state.rst | 21 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/table.rst | 10 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/thread.rst | 30 | ||||
-rw-r--r-- | 3rdparty/sol2/docs/source/api/usertype.rst | 3 |
8 files changed, 118 insertions, 6 deletions
diff --git a/3rdparty/sol2/docs/source/api/api-top.rst b/3rdparty/sol2/docs/source/api/api-top.rst index 4dac922becf..ebeabf3ee3b 100644 --- a/3rdparty/sol2/docs/source/api/api-top.rst +++ b/3rdparty/sol2/docs/source/api/api-top.rst @@ -32,6 +32,7 @@ Browse the various function and classes :doc:`Sol<../index>` utilizes to make yo optional this_state variadic_args + as_args overload property var diff --git a/3rdparty/sol2/docs/source/api/as_args.rst b/3rdparty/sol2/docs/source/api/as_args.rst new file mode 100644 index 00000000000..8e323fdfaba --- /dev/null +++ b/3rdparty/sol2/docs/source/api/as_args.rst @@ -0,0 +1,50 @@ +as_args +======= +turn an iterable argument into multiple arguments +------------------------------------------------- + +.. code-block:: cpp + + template <typename T> + as_args_t { ... }; + + template <typename T> + as_args_t<T> as_args( T&& ); + + +``sol::as_args`` is a function that that takes an iterable and turns it into multiple arguments to a function call. It forwards its arguments, and is meant to be used as shown below: + +.. code-block:: cpp + :caption: as_args.c++ + + #define SOL_CHECK_ARGUMENTS + #include <sol.hpp> + + #include <vector> + #include <set> + + int main(int argc, const char* argv[]) { + + sol::state lua; + lua.open_libraries(); + + lua.script("function f (a, b, c, d) print(a, b, c, d) end"); + + sol::function f = lua["f"]; + + std::vector<int> v2{ 3, 4 }; + f(1, 2, sol::as_args(v2)); + + std::set<int> v4{ 3, 1, 2, 4 }; + f(sol::as_args(v4)); + + int v3[] = { 2, 3, 4 }; + f(1, sol::as_args(v3)); + + return 0; + } + + +It is basically implemented as a `one-way customization point`_. For more information about customization points, see the :doc:`tutorial on how to customize Sol to work with your types<../tutorial/customization>`. + +.. _one-way customization point: https://github.com/ThePhD/sol2/blob/develop/sol/as_args.hpp diff --git a/3rdparty/sol2/docs/source/api/reference.rst b/3rdparty/sol2/docs/source/api/reference.rst index 37886dc2300..57869de7db0 100644 --- a/3rdparty/sol2/docs/source/api/reference.rst +++ b/3rdparty/sol2/docs/source/api/reference.rst @@ -20,8 +20,11 @@ members :caption: constructor: reference reference(lua_State* L, int index = -1); + reference(lua_State* L, ref_index index); + template <typename Object> + reference(Object&& o); -Creates a reference from the Lua stack at the specified index, saving it into the metatable registry. This constructor is exposed on all types that derive from ``sol::reference``. +The first constructor creates a reference from the Lua stack at the specified index, saving it into the metatable registry. The second attemtps to register something that already exists in the registry. The third attempts to reference a pre-existing object and create a reference to it. These constructors are exposed on all types that derive from ``sol::reference``, meaning that you can grab tables, functions, and coroutines from the registry, stack, or from other objects easily. .. code-block:: cpp :caption: function: push referred-to element from the stack diff --git a/3rdparty/sol2/docs/source/api/resolve.rst b/3rdparty/sol2/docs/source/api/resolve.rst index 193e2fae80f..b1ceffd0134 100644 --- a/3rdparty/sol2/docs/source/api/resolve.rst +++ b/3rdparty/sol2/docs/source/api/resolve.rst @@ -19,6 +19,7 @@ utility to pick overloaded C++ function calls int overloaded(int x, int y, int z); struct thing { + int overloaded() const; int overloaded(int x); int overloaded(int x, int y); int overloaded(int x, int y, int z); @@ -33,8 +34,9 @@ You can disambiguate them using ``resolve``: auto two_argument_func = resolve<int(int, int)>( overloaded ); auto three_argument_func = resolve<int(int, int, int)>( overloaded ); auto member_three_argument_func = resolve<int(int, int, int)>( &thing::overloaded ); + auto member_zero_argument_const_func = resolve<int() const>( &thing::overloaded ); -This resolution becomes useful when setting functions on a :doc:`table<table>` or :doc:`state_view<state>`: +It is *important* to note that ``const`` is placed at the end for when you desire const overloads. You will get compiler errors if you are not specific and do not properly disambiguate for const member functions. This resolution also becomes useful when setting functions on a :doc:`table<table>` or :doc:`state_view<state>`: .. code-block:: cpp :linenos: diff --git a/3rdparty/sol2/docs/source/api/state.rst b/3rdparty/sol2/docs/source/api/state.rst index a0838fbf110..b1b17a3cc67 100644 --- a/3rdparty/sol2/docs/source/api/state.rst +++ b/3rdparty/sol2/docs/source/api/state.rst @@ -102,13 +102,32 @@ Get either the global table or the Lua registry as a :doc:`sol::table<table>`, w .. code-block:: cpp - :caption: function: Lua set_panic + :caption: function: set_panic :name: set-panic void set_panic(lua_CFunction panic); Overrides the panic function Lua calls when something unrecoverable or unexpected happens in the Lua VM. Must be a function of the that matches the ``int(lua_State*)`` function signature. + +.. code-block:: cpp + :caption: function: memory_used + :name: memory-used + + std::size_t memory_used() const; + +Returns the amount of memory used *in bytes* by the Lua State. + + +.. code-block:: cpp + :caption: function: collect_garbage + :name: collect-garbage + + void collect_garbage(); + +Attempts to run the garbage collector. Note that this is subject to the same rules as the Lua API's collect_garbage function: memory may or may not be freed, depending on dangling references or other things, so make sure you don't have tables or other stack-referencing items currently alive or referenced that you want to be collected. + + .. code-block:: cpp :caption: function: make a table diff --git a/3rdparty/sol2/docs/source/api/table.rst b/3rdparty/sol2/docs/source/api/table.rst index b5a946487de..25197b126c7 100644 --- a/3rdparty/sol2/docs/source/api/table.rst +++ b/3rdparty/sol2/docs/source/api/table.rst @@ -148,7 +148,15 @@ Sets a previously created usertype with the specified ``key`` into the table. No table_iterator cbegin() const; table_iterator cend() const; -Provides `input iterators`_ for a table. This allows tables to work with single-pass, input-only algorithms (like ``std::for_each``). +Provides (what can barely be called) `input iterators`_ for a table. This allows tables to work with single-pass, input-only algorithms (like ``std::for_each``). Note that manually getting an iterator from ``.begin()`` without a ``.end()`` or using postfix incrementation (``++mytable.begin()``) will lead to poor results. The Lua stack is manipulated by an iterator and thusly not performing the full iteration once you start is liable to ruin either the next iteration or break other things subtly. Use a C++11 ranged for loop, ``std::for_each``, or other algorithims which pass over the entire collection at least once and let the iterators fall out of scope. + +.. _iteration_note: +.. warning:: + + The iterators you use to walk through a ``sol::table`` are NOT guaranteed to iterate in numeric order, or ANY kind of order. They may iterate backwards, forwards, in the style of cuckoo-hashing, by accumulating a visited list while calling ``rand()`` to find the next target, or some other crazy scheme. Now, no implementation would be crazy, but it is behavior specifically left undefined because there are many ways that your Lua package can implement the table type. + + Iteration order is NOT something you should rely on. If you want to figure out the length of a table, call the length operation (``int count = mytable.size();`` using the sol API) and then iterate from ``1`` to ``count`` (inclusive of the value of count, because Lua expects iteration to work in the range of ``[1, count]``). This will save you some headaches in the future when the implementation decides not to iterate in numeric order. + .. code-block:: cpp :caption: function: iteration with a function diff --git a/3rdparty/sol2/docs/source/api/thread.rst b/3rdparty/sol2/docs/source/api/thread.rst index 1a713f973b4..b7349d97efb 100644 --- a/3rdparty/sol2/docs/source/api/thread.rst +++ b/3rdparty/sol2/docs/source/api/thread.rst @@ -9,15 +9,36 @@ a separate state that can contain and run functions ``sol::thread`` is a separate runnable part of the Lua VM that can be used to execute work separately from the main thread, such as with :doc:`coroutines<coroutine>`. To take a table or a coroutine and run it specifically on the ``sol::thread`` you either pulled out of lua or created, just get that function through the :ref:`state of the thread<thread_state>` +.. note:: + + A CPU thread is not always equivalent to a new thread in Lua: ``std::this_thread::get_id()`` can be the same for 2 callbacks that have 2 distinct Lua threads. In order to know which thread a callback was called in, hook into :doc:`sol::this_state<this_state>` from your Lua callback and then construct a ``sol::thread``, passing in the ``sol::this_state`` for both the first and last arguments. Then examine the results of the status and ``is_...`` calls below. + +free function +------------- + +.. code-block:: cpp + :caption: function: main_thread + + main_thread(lua_State* current, lua_State* backup_if_bad_platform = nullptr); + +The function ``sol::main_thread( ... )`` retrieves the main thread of the application on Lua 5.2 and above *only*. It is designed for code that needs to be multithreading-aware (e.g., uses multiple :doc:`threads<thread>` and :doc:`coroutines<coroutine>`). + +.. warning:: + + This code function will be present in Lua 5.1/LuaJIT, but only have proper behavior when given a single argument on Lua 5.2 and beyond. Lua 5.1 does not support retrieving the main thread from its registry, and therefore it is entirely suggested if you are writing cross-platform Lua code that you must store the main thread of your application in some global storage accessible somewhere. Then, pass this item into the ``sol::main_thread( possibly_thread_state, my_actual_main_state )`` and it will select that ``my_actual_main_state`` every time. If you are not going to use Lua 5.1 / LuaJIT, you can ignore the last parameter. + + members ------- .. code-block:: cpp :caption: constructor: thread + thread(stack_reference r); thread(lua_State* L, int index = -1); + thread(lua_State* L, lua_State* actual_thread); -Takes a thread from the Lua stack at the specified index and allows a person to use all of the abstractions therein. +Takes a thread from the Lua stack at the specified index and allows a person to use all of the abstractions therein. It can also take an actual thread state to make a thread from that as well. .. code-block:: cpp :caption: function: view into thread_state()'s state @@ -43,6 +64,13 @@ This function retrieves the ``lua_State*`` that represents the thread. Retrieves the :doc:`thread status<types>` that describes the current state of the thread. .. code-block:: cpp + :caption: main thread status + + bool is_main_thread () const; + +Checks to see if the thread is the main Lua thread. + +.. code-block:: cpp :caption: function: thread creation :name: thread-create diff --git a/3rdparty/sol2/docs/source/api/usertype.rst b/3rdparty/sol2/docs/source/api/usertype.rst index 2fa73a320a2..bd941c527dc 100644 --- a/3rdparty/sol2/docs/source/api/usertype.rst +++ b/3rdparty/sol2/docs/source/api/usertype.rst @@ -170,9 +170,10 @@ If you don't specify any constructor options at all and the type is `default_con * ``{anything}, {some_factory_function}`` - Essentially binds whatever the function is to name ``{anything}`` - When used WITH the ``sol::no_constructor`` option above (e.g. ``"new", sol::no_constructor`` and after that having ``"create", &my_creation_func``), one can remove typical constructor avenues and then only provide specific factory functions. Note that this combination is similar to using the ``sol::factories`` method mentioned earlier in this list. To control the destructor as well, see further below -* ``sol::call_constructor, {valid function / constructor / initializer / factory}`` +* ``sol::call_constructor, {valid constructor / initializer / factory}`` - The purpose of this is to enable the syntax ``local v = my_class( 24 )`` and have that call a constructor; it has no other purpose - This is compatible with luabind, kaguya and other Lua library syntaxes and looks similar to C++ syntax, but the general consensus in Programming with Lua and other places is to use a function named ``new`` + - Note that with the ``sol::call_constructor`` key, a construct type above must be specified. A free function without it will pass in the metatable describing this object as the first argument without that distinction, which can cause strange runtime errors. usertype destructor options +++++++++++++++++++++++++++ |