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.mo...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
