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/thread.rst | |
parent | 29df715138452ee18ba19ec4b07e18c4b3185de7 (diff) |
Update sol2 (nw)
Diffstat (limited to '3rdparty/sol2/docs/source/api/thread.rst')
-rw-r--r-- | 3rdparty/sol2/docs/source/api/thread.rst | 30 |
1 files changed, 29 insertions, 1 deletions
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 |