[PATCH 1/2] barrier: Remove leftover semaphore remnants

[Gedare Bloom]

On Tue, Oct 1, 2019 at 3:53 PM Gedare Bloom <gedare at rtems.org> wrote:
>
> On Wed, Sep 4, 2019 at 3:36 PM Martin Erik Werner
> <martinerikwerner at gmail.com> wrote:
> >
> > Remove various incorrect references to "lock" and "obtain" and to an
> > option set which is not part of the barrier interface.
> >
> > It looks like the barrier documentation was started based on a copy of
> > the semaphore documentation and these things are surviving remnants.
> >
> > Also remove an unfinished sentence in the barrier wait description,
> > since the intended information is already provided in the under the NOTE
> > label.
> Thanks for your contribution!  I have a few minor comments:
>
> > ---
> >  c-user/barrier_manager.rst | 38 +++++++-------------------------------
> >  1 file changed, 7 insertions(+), 31 deletions(-)
> >
> > diff --git a/c-user/barrier_manager.rst b/c-user/barrier_manager.rst
> > index b0bf3bf..e5d69b0 100644
> > --- a/c-user/barrier_manager.rst
> > +++ b/c-user/barrier_manager.rst
> > @@ -324,8 +324,7 @@ NOTES:
> >
> >  .. _rtems_barrier_wait:
> >
> > -.. index:: obtain a barrier
> > -.. index:: lock a barrier
> > +.. index:: wait at a barrier
> >  .. index:: rtems_barrier_wait
> >
> >  BARRIER_WAIT - Wait at a barrier
> > @@ -356,14 +355,11 @@ DIRECTIVE STATUS CODES:
> >
> >  DESCRIPTION:
> >
> > -    This directive acquires the barrier specified by ``id``.  The
> > -    ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter
> > -    indicate whether the calling task wants to wait for the barrier to become
> > -    available or return immediately if the barrier is not currently available.
> > -    With either ``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier
> > -    count is positive, then it is decremented by one and the barrier is
> > -    successfully acquired by returning immediately with a successful return
> > -    code.
> > +    This directive waits at the barrier specified by ``id``.  The timeout
> > +    parameter specifies the maximum interval the calling task is willing to be
> > +    blocked waiting for the barrier.  If it is set to ``RTEMS_NO_TIMEOUT``,
> > +    then the calling task will wait forever.  If the barrier is available or
> 1. "will wait forever" -> "will wait forever if it doesn't get
> released" or something more precise, even just "may wait forever"
> 2. I'm not quite sure what "available" means in this context. Maybe
> "open" is a better word?
>
I guess "available" is the wording that has been used throughout.
Again, probably due to inheriting from the semaphore documentation. I
think "open/closed" is more precise when describing a barrier, but
available is OK if it is consistently applied.

I would still like the fix on #1, even though that was not introduced
by you just copied from elsewhere, it is good to improve it at the
same time.

> > +    the ``RTEMS_NO_WAIT`` option component is set, then timeout is ignored.
> >
> >      Conceptually, the calling task should always be thought of as blocking when
> >      it makes this call and being unblocked when the barrier is released.  If
> > @@ -372,24 +368,7 @@ DESCRIPTION:
> >      callers will block except for the one which is the Nth task which trips the
> >      automatic release condition.
> >
> > -    The timeout parameter specifies the maximum interval the calling task is
> > -    willing to be blocked waiting for the barrier.  If it is set to
> > -    ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.  If the
> > -    barrier is available or the ``RTEMS_NO_WAIT`` option component is set, then
> > -    timeout is ignored.
> > -
> >  NOTES:
> > -
> > -    The following barrier acquisition option constants are defined by RTEMS:
> > -
> > -    .. list-table::
> > -     :class: rtems-table
> > -
> > -     * - ``RTEMS_WAIT``
> > -       - task will wait for barrier (default)
> > -     * - ``RTEMS_NO_WAIT``
> > -       - task should not wait
> > -
> >      A clock tick is required to support the timeout functionality of this
> >      directive.
> >
> > @@ -399,7 +378,6 @@ NOTES:
> >
> >  .. _rtems_barrier_release:
> >
> > -.. index:: wait at a barrier
> >  .. index:: release a barrier
> >  .. index:: rtems_barrier_release
> >
> > @@ -425,9 +403,7 @@ DIRECTIVE STATUS CODES:
> >
> >  DESCRIPTION:
> >      This directive releases the barrier specified by id.  All tasks waiting at
> > -    the barrier will be unblocked.  If the running task's preemption mode is
> > -    enabled and one of the unblocked tasks has a higher priority than the
> > -    running task.
> > +    the barrier will be unblocked.
> >
> >  NOTES:
> >      The calling task may be preempted if it causes a higher priority task to be
> > --
> > 2.11.0
> >
> > _______________________________________________
> > devel mailing list
> > devel at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel