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

[Kinsey Moore]

On Tue, Jun 27, 2023 at 4:05 PM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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?
>

A delay specified in some subunit of seconds instead of clock ticks.

>
> 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.
>

The issue with specifying "interval" is that "time interval" is a common
phrase in general and a clock tick can vary depending on application
configuration. While the use of "interval" isn't necessarily wrong, "time
interval" is very misleading in this context and could easily be assumed.
Would "clock tick interval" be reasonable for clarity as a way to distance
the verbiage from "time interval"?


> >
> >   .. 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}.
>

Will do.

Kinsey
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20230627/e8397248/attachment.htm>