[PATCH v2 1/2] c-user: Document task life states
chrisj at rtems.org
Thu Jul 28 00:06:39 UTC 2022
Nice and OK to push. A minor point below...
On 27/7/2022 7:30 pm, Sebastian Huber wrote:
> Update #4679.
> c-user/task/background.rst | 53 +++++++++++++++++++++++++++++++++++++-
> 1 file changed, 52 insertions(+), 1 deletion(-)
> diff --git a/c-user/task/background.rst b/c-user/task/background.rst
> index da6cabf..df38356 100644
> --- a/c-user/task/background.rst
> +++ b/c-user/task/background.rst
> @@ -1,6 +1,6 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
> -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
> +.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
> .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
> @@ -233,6 +233,57 @@ the task will execute at interrupt level n.
> The set of default modes may be selected by specifying the
> ``RTEMS_DEFAULT_MODES`` constant.
> +.. index:: task life states
> +Task Life States
> +Independent of the task state with respect to the scheduler, the task life is
> +determined by several orthogonal states:
> +* *protected* or *unprotected*
> +* *deferred life changes* or *no deferred life changes*
> +* *restarting* or *not restarting*
> +* *terminating* or *not terminating*
> +* *detached* or *not detached*
> +While the task life is *protected*, asynchronous task restart and termination
> +requests are blocked. A task may still restart or terminate itself. All tasks
> +are created with an unprotected task life.
> The task life protection is used by
> +the system to prevent that system resources are affected by asynchronous task
> +restart and termination requests.
Is this suppose to be:
The task life protection is used by the system to prevent system resources being
affected by asynchronous task restart and termination requests.
> The task life protection can be enabled
> +(``PTHREAD_CANCEL_DISABLE``) or disabled (``PTHREAD_CANCEL_ENABLE``) for the
> +calling task through the ``pthread_setcancelstate()`` directive.
> +While *deferred life changes* are enabled, asynchronous task restart and
> +termination requests are delayed until the task performs a life change itself
> +or calls ``pthread_testcancel()``. Cancellation points are not implemented in
> +RTEMS. Deferred task life changes can be enabled (``PTHREAD_CANCEL_DEFERRED``)
> +or disabled (``PTHREAD_CANCEL_ASYNCHRONOUS``) for the calling task through the
> +``pthread_setcanceltype()`` directive. Classic API tasks are created with
> +deferred life changes disabled. POSIX threads are created with deferred life
> +changes enabled.
> +A task is made *restarting* by issuing a task restart request through the
> +:ref:`InterfaceRtemsTaskRestart` directive.
> +A task is made *terminating* by issuing a task termination request through the
> +:ref:`InterfaceRtemsTaskExit`, :ref:`InterfaceRtemsTaskDelete`,
> +``pthread_exit()``, and ``pthread_cancel()`` directives.
> +When a *detached* task terminates, the termination procedure completes without
> +the need for another task to join with the terminated task. Classic API tasks
> +are created as not detached. The detached state of created POSIX threads is
> +determined by the thread attributes. They are created as not detached by
> +default. The calling task is made detached through the ``pthread_detach()``
> +directive. The :ref:`InterfaceRtemsTaskExit` directive and self deletion
> +though :ref:`InterfaceRtemsTaskDelete` directive make the calling task
> .. index:: task arguments
> .. index:: task prototype
More information about the devel