<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Oct 1, 2019, 5:07 PM Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Tue, Oct 1, 2019 at 3:53 PM Gedare Bloom <<a href="mailto:gedare@rtems.org" target="_blank" rel="noreferrer">gedare@rtems.org</a>> wrote:<br>
><br>
> On Wed, Sep 4, 2019 at 3:36 PM Martin Erik Werner<br>
> <<a href="mailto:martinerikwerner@gmail.com" target="_blank" rel="noreferrer">martinerikwerner@gmail.com</a>> wrote:<br>
> ><br>
> > Remove various incorrect references to "lock" and "obtain" and to an<br>
> > option set which is not part of the barrier interface.<br>
> ><br>
> > It looks like the barrier documentation was started based on a copy of<br>
> > the semaphore documentation and these things are surviving remnants.<br>
> ><br>
> > Also remove an unfinished sentence in the barrier wait description,<br>
> > since the intended information is already provided in the under the NOTE<br>
> > label.<br>
> Thanks for your contribution! I have a few minor comments:<br>
><br>
> > ---<br>
> > c-user/barrier_manager.rst | 38 +++++++-------------------------------<br>
> > 1 file changed, 7 insertions(+), 31 deletions(-)<br>
> ><br>
> > diff --git a/c-user/barrier_manager.rst b/c-user/barrier_manager.rst<br>
> > index b0bf3bf..e5d69b0 100644<br>
> > --- a/c-user/barrier_manager.rst<br>
> > +++ b/c-user/barrier_manager.rst<br>
> > @@ -324,8 +324,7 @@ NOTES:<br>
> ><br>
> > .. _rtems_barrier_wait:<br>
> ><br>
> > -.. index:: obtain a barrier<br>
> > -.. index:: lock a barrier<br>
> > +.. index:: wait at a barrier<br>
> > .. index:: rtems_barrier_wait<br>
> ><br>
> > BARRIER_WAIT - Wait at a barrier<br>
> > @@ -356,14 +355,11 @@ DIRECTIVE STATUS CODES:<br>
> ><br>
> > DESCRIPTION:<br>
> ><br>
> > - This directive acquires the barrier specified by ``id``. The<br>
> > - ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter<br>
> > - indicate whether the calling task wants to wait for the barrier to become<br>
> > - available or return immediately if the barrier is not currently available.<br>
> > - With either ``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier<br>
> > - count is positive, then it is decremented by one and the barrier is<br>
> > - successfully acquired by returning immediately with a successful return<br>
> > - code.<br>
> > + This directive waits at the barrier specified by ``id``. The timeout<br>
> > + parameter specifies the maximum interval the calling task is willing to be<br>
> > + blocked waiting for the barrier. If it is set to ``RTEMS_NO_TIMEOUT``,<br>
> > + then the calling task will wait forever. If the barrier is available or<br>
> 1. "will wait forever" -> "will wait forever if it doesn't get<br>
> released" or something more precise, even just "may wait forever"<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">Will wait until the barrier is released/opened. Then add there is no option for no wait as found in other APIs. </div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
> 2. I'm not quite sure what "available" means in this context. Maybe<br>
> "open" is a better word?<br>
><br>
I guess "available" is the wording that has been used throughout.<br>
Again, probably due to inheriting from the semaphore documentation. I<br>
think "open/closed" is more precise when describing a barrier, but<br>
available is OK if it is consistently applied.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">Open/closed is better. I think of a barrier as the starting gates at a horse race. Horses arrive and wait while the gates are closed. When the race starts, all gates are opened and the horses are released. </div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
I would still like the fix on #1, even though that was not introduced<br>
by you just copied from elsewhere, it is good to improve it at the<br>
same time.<br>
<br>
> > + the ``RTEMS_NO_WAIT`` option component is set, then timeout is ignored.<br>
> ><br>
> > Conceptually, the calling task should always be thought of as blocking when<br>
> > it makes this call and being unblocked when the barrier is released. If<br>
> > @@ -372,24 +368,7 @@ DESCRIPTION:<br>
> > callers will block except for the one which is the Nth task which trips the<br>
> > automatic release condition.<br>
> ><br>
> > - The timeout parameter specifies the maximum interval the calling task is<br>
> > - willing to be blocked waiting for the barrier. If it is set to<br>
> > - ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the<br>
> > - barrier is available or the ``RTEMS_NO_WAIT`` option component is set, then<br>
> > - timeout is ignored.<br>
> > -<br>
> > NOTES:<br>
> > -<br>
> > - The following barrier acquisition option constants are defined by RTEMS:<br>
> > -<br>
> > - .. list-table::<br>
> > - :class: rtems-table<br>
> > -<br>
> > - * - ``RTEMS_WAIT``<br>
> > - - task will wait for barrier (default)<br>
> > - * - ``RTEMS_NO_WAIT``<br>
> > - - task should not wait<br>
> > -<br>
> > A clock tick is required to support the timeout functionality of this<br>
> > directive.<br>
> ><br>
> > @@ -399,7 +378,6 @@ NOTES:<br>
> ><br>
> > .. _rtems_barrier_release:<br>
> ><br>
> > -.. index:: wait at a barrier<br>
> > .. index:: release a barrier<br>
> > .. index:: rtems_barrier_release<br>
> ><br>
> > @@ -425,9 +403,7 @@ DIRECTIVE STATUS CODES:<br>
> ><br>
> > DESCRIPTION:<br>
> > This directive releases the barrier specified by id. All tasks waiting at<br>
> > - the barrier will be unblocked. If the running task's preemption mode is<br>
> > - enabled and one of the unblocked tasks has a higher priority than the<br>
> > - running task.<br>
> > + the barrier will be unblocked.<br>
> ><br>
> > NOTES:<br>
> > The calling task may be preempted if it causes a higher priority task to be<br>
> > --<br>
> > 2.11.0<br>
> ><br>
> > _______________________________________________<br>
> > devel mailing list<br>
> > <a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
> > <a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div></div>