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

[Sebastian Huber]

On 27.06.23 22:18, Kinsey Moore wrote:
> diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
> index c082b51..3334679 100644
> --- a/c-user/task/directives.rst
> +++ b/c-user/task/directives.rst
> @@ -1475,15 +1475,15 @@ 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 number of ticks
> +.. index:: wake up after a number of ticks
>   
>   .. _InterfaceRtemsTaskWakeAfter:
>   
>   rtems_task_wake_after()
>   -----------------------
>   
> -Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the
> +Wakes up after a number of :term:`clock ticks <clock tick>` or yields the
>   processor.
>   
>   .. rubric:: CALLING SEQUENCE:
> @@ -1502,10 +1502,12 @@ processor.
>   
>   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
> +requested number of ticks 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
> -:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.
> +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.  Applications requiring use of a
> +time base instead of system ticks should make use of ``nanosleep()`` or
> +``clock_nanosleep()``.

What is a time base?

nanosleep() has the same issues as rtems_task_wake_after(). If you want 
to wait for fixed intervals, then you have to use clock_nanosleep() with 
TIMER_ABSTIME and CLOCK_MONOTONIC.

The wording with the interval is not really wrong. Only the clock 
resolution is a bit coarse (clock ticks). I guess the real problem is 
that if you want to implement a periodic task with

while (1) {
	f();
	rtems_task_wake_after(period);
}

then this doesn't work if the time between calls to 
rtems_task_wake_after() varies within the range of clock ticks. This can 
be fixed by using clock_nanosleep() with TIMER_ABSTIME and CLOCK_MONOTONIC.

>   
>   .. rubric:: RETURN VALUES:
>   

Could you please update

https://git.rtems.org/rtems-central/tree/spec/rtems/task/if/wake-after.yml

since this will keep also the Doxygen up to date.

For clock_nanosleep() references, use ${/c/if/clock-nanosleep:/name}.

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/