mirror of
https://github.com/Dasharo/zephyr.git
synced 2026-03-06 14:57:20 -08:00
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:
@@ -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
|
||||
===============
|
||||
|
||||
|
||||
Reference in New Issue
Block a user