doc: Clean up docs on thread termination behavior

Discussion about how to re-spawn threads led to the discovery that our
documentation on exactly when that was legal was ambiguous and
confusing.  Rewrite it to be explicit.

Fixes #28970

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This commit is contained in:
Andy Ross
2021-01-21 12:38:38 -08:00
committed by Anas Nashif
parent ecc57a12a6
commit 8ccd506966
+10 -4
View File
@@ -82,16 +82,22 @@ A thread that terminates is responsible for releasing any shared resources
it may own (such as mutexes and dynamically allocated memory)
prior to returning, since the kernel does *not* reclaim them automatically.
.. note::
The kernel does not currently make any claims regarding an application's
ability to respawn a thread that terminates.
In some cases a thread may want to sleep until another thread terminates.
This can be accomplished with the :c:func:`k_thread_join` API. This
will block the calling thread until either the timeout expires, the target
thread self-exits, or the target thread aborts (either due to a
k_thread_abort() call or triggering a fatal error).
Once a thread has terminated, the kernel guarantees that no use will
be made of the thread struct. The memory of such a struct can then be
re-used for any purpose, including spawning a new thread. Note that
the thread must be fully terminated, which presents race conditions
where a thread's own logic signals completion which is seen by another
thread before the kernel processing is complete. Under normal
circumstances, application code should use :c:func:`k_thread_join` or
:c:func:`k_thread_abort` to synchronize on thread termination state
and not rely on signaling from within application logic.
Thread Aborting
===============