[PATCH rtems-docs v3] c-user: Update references to rtems_task_wake_after

Wed Jul 5 22:50:42 UTC 2023

This looks good to me. The only other thing worth mentioning, that is
not mentioned, is that this directive provides an "upper bound"
(maximum sleeping time) on how long a task might be non-schedulable,
whereas other sleep directives tend to provide a "lower bound"
(minimum sleeping time). At any rate, you've captured the main point.

On Wed, Jul 5, 2023 at 2:48 PM Kinsey Moore <kinsey.moore at oarcorp.com> wrote:
>
> rtems_task_wake_after takes a parameter in terms of a count of clock
> ticks and not a measure in a subunit of seconds. This updates
> documentation to reflect that. This also makes obvious the caveat about
> the first tick wait not being a whole tick and points the user at a
> replacement for better accuracy.
>
> Updates #4772
> ---
>  c-user/scheduling-concepts/background.rst |  8 +++----
>  c-user/task/directives.rst                | 27 ++++++++++++++---------
>  c-user/task/introduction.rst              |  4 ++--
>  c-user/task/operations.rst                |  6 ++---
>  4 files changed, 25 insertions(+), 20 deletions(-)
>
> diff --git a/c-user/scheduling-concepts/background.rst b/c-user/scheduling-concepts/background.rst
> index 1fe7089..38b77ee 100644
> --- a/c-user/scheduling-concepts/background.rst
> +++ b/c-user/scheduling-concepts/background.rst
> @@ -160,7 +160,7 @@ Manual Round-Robin
>
>  The final mechanism for altering the RTEMS scheduling algorithm is called
>  manual round-robin.  Manual round-robin is invoked by using
> -the ``rtems_task_wake_after`` directive with a time interval of
> +the ``rtems_task_wake_after`` directive with a ``ticks`` parameter of
>  ``RTEMS_YIELD_PROCESSOR``.  This allows a task to give up the processor and be
>  immediately returned to the ready chain at the end of its priority group.  If
>  no other tasks of the same priority are ready to run, then the task does not
> @@ -243,7 +243,7 @@ of the following conditions:
>    option and the requested semaphore is unavailable.
>
>  - The running task issues a ``rtems_task_wake_after`` directive which blocks
> -  the task for the given time interval.  If the time interval specified is
> +  the task for the given count of ticks.  If the count of ticks specified is
>    zero, the task yields the processor and remains in the ready state.
>
>  - The running task issues a ``rtems_task_wake_when`` directive which blocks the
> @@ -280,8 +280,8 @@ conditions:
>  - A running task issues a ``rtems_semaphore_release`` directive which releases
>    the semaphore on which the blocked task is waiting.
>
> -- A timeout interval expires for a task which was blocked by a call to the
> -  ``rtems_task_wake_after`` directive.
> +- The requested count of ticks has elapsed for a task which was blocked by a
> +  call to the ``rtems_task_wake_after`` directive.
>
>  - A timeout period expires for a task which blocked by a call to the
>    ``rtems_task_wake_when`` directive.
> diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
> index c082b51..ea2337a 100644
> --- a/c-user/task/directives.rst
> +++ b/c-user/task/directives.rst
> @@ -1475,16 +1475,16 @@ The following constraints apply to this directive:
>      \clearpage
>
>  .. index:: rtems_task_wake_after()
> -.. index:: delay a task for an interval
> -.. index:: wake up after an interval
> +.. index:: delay a task for a count of clock ticks
> +.. index:: wake up after a count of clock ticks
>
>  .. _InterfaceRtemsTaskWakeAfter:
>
>  rtems_task_wake_after()
>  -----------------------
>
> -Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the
> -processor.
> +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or
> +yields the processor.
>
>  .. rubric:: CALLING SEQUENCE:
>
> @@ -1495,16 +1495,16 @@ processor.
>  .. rubric:: PARAMETERS:
>
>  ``ticks``
> -    This parameter is the interval in :term:`clock ticks <clock tick>` to delay
> +    This parameter is the count of :term:`clock ticks <clock tick>` to delay
>      the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor.
>
>  .. rubric:: DESCRIPTION:
>
> -This directive blocks the calling task for the specified ``ticks`` of clock
> -ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`.  When the
> -requested interval has elapsed, the task is made ready.  The clock tick
> -directives automatically updates the delay period.  The calling task may give
> -up the processor and remain in the ready state by specifying a value of
> +This directive blocks the calling task for the specified ``ticks`` count of
> +clock ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When
> +the requested count of ticks have occurred, the task is made ready.  The clock
> +tick directives automatically update the delay period.  The calling task may
> +give up the processor and remain in the ready state by specifying a value of
>  :c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.
>
>  .. rubric:: RETURN VALUES:
> @@ -1516,7 +1516,12 @@ up the processor and remain in the ready state by specifying a value of
>
>  Setting the system date and time with the :ref:`InterfaceRtemsClockSet`
>  directive and similar directives which set :term:`CLOCK_REALTIME` have no
> -effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task.
> +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task.  The delay until
> +first clock tick will never be a whole clock tick interval since this directive
> +will never excute exactly on a clock tick.  Applications requiring use of a
> +clock (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make
> +use of `clock_nanosleep()
> +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_.
>
>  .. rubric:: CONSTRAINTS:
>
> diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst
> index 6f5ff4d..4a41acd 100644
> --- a/c-user/task/introduction.rst
> +++ b/c-user/task/introduction.rst
> @@ -84,8 +84,8 @@ and administer tasks. The directives provided by the Task Manager are:
>  * :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the
>    calling task.
>
> -* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after an interval in
> -  :term:`clock ticks <clock tick>` or yields the processor.
> +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock
> +  ticks <clock tick>` have occurred or yields the processor.
>
>  * :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified.
>
> diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst
> index 6308d7b..438eea5 100644
> --- a/c-user/task/operations.rst
> +++ b/c-user/task/operations.rst
> @@ -75,9 +75,9 @@ Delaying the Currently Executing Task
>  -------------------------------------
>
>  The ``rtems_task_wake_after`` directive creates a sleep timer which allows a
> -task to go to sleep for a specified interval.  The task is blocked until the
> -delay interval has elapsed, at which time the task is unblocked.  A task
> -calling the ``rtems_task_wake_after`` directive with a delay interval of
> +task to go to sleep for a specified count of clock ticks.  The task is blocked
> +until the count of clock ticks has elapsed, at which time the task is unblocked.
> +A task calling the ``rtems_task_wake_after`` directive with a delay of
>  ``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready
>  task of equal or greater priority and remain ready to execute.
>
> --
> 2.30.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel