[PATCH] c-user: Document new rtems_task_delete() behaviour

Sebastian Huber sebastian.huber at embedded-brains.de
Tue Jul 26 10:07:29 UTC 2022

Update #4679.
 c-user/task/directives.rst | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
index 64b591d..9f9ea45 100644
--- a/c-user/task/directives.rst
+++ b/c-user/task/directives.rst
@@ -805,16 +805,28 @@ specified by ``id``.
     The directive was called from within interrupt context.
+    The task termination procedure was started, however, waiting for the
+    terminating task would have resulted in a deadlock.
     The task resided on a remote node.
 .. rubric:: NOTES:
-RTEMS stops the execution of the task and reclaims the stack memory, any
-allocated delay or timeout timers, the TCB, and, if the task is
-:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS
-explicitly does not reclaim the following resources: region segments, partition
-buffers, semaphores, timers, or rate monotonic periods.
+The task deletion is done in several steps.  Firstly, the task is marked as
+terminating.  While the task life of the terminating task is protected, it
+executes normally until it disables the task life protection or it deletes
+itself.  A terminating task will eventually stop its normal execution and start
+its termination procedure.  The procedure executes in the context of the
+terminating task.  It involves the destruction of POSIX key values and running
+the task termination user extensions.  Once the task termination procedure is
+done, the execution of the task is stopped and task-specific resources are
+reclaimed by the system, such as the stack memory, any allocated delay or
+timeout timers, the TCB, and, if the task is :c:macro:`RTEMS_FLOATING_POINT`,
+its floating point context area. RTEMS explicitly does not reclaim the
+following resources: region segments, partition buffers, semaphores, timers, or
+rate monotonic periods.
 A task is responsible for releasing its resources back to RTEMS before
 deletion.  To insure proper deallocation of resources, a task should not be
@@ -824,11 +836,16 @@ resources before deletion.  A task can be directed to release its resources and
 delete itself by restarting it with a special argument or by sending it a
 message, an event, or a signal.
-Deletion of the current task (:c:macro:`RTEMS_SELF`) will force RTEMS to select
+Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select
 another task to execute.
 The :term:`TCB` for the deleted task is reclaimed by RTEMS.
+When a task other than the calling task is deleted, the calling task waits
+until the task termination procedure of the other task is done.  The
+terminating task inherits the :term:`eligible priorities <eligible priority>`
+of the calling task.
 When a global task is deleted, the task identifier must be transmitted to every
 node in the system for deletion from the local copy of the global object table.

More information about the devel mailing list