[PATCH 1/2] barrier: Remove leftover semaphore remnants
Martin Erik Werner
martinerikwerner at gmail.com
Sat Oct 12 00:12:46 UTC 2019
On Wed, 2019-10-02 at 17:00 -0500, Joel Sherrill wrote:
>
>
> On Wed, Oct 2, 2019 at 2:52 PM Martin Erik Werner <
> martinerikwerner at gmail.com> wrote:
(...)
> > On Tue, 2019-10-01 at 18:02 -0500, Joel Sherrill wrote:
> > >
> > >
> > > On Tue, Oct 1, 2019, 5:07 PM Gedare Bloom <gedare at rtems.org>
> > wrote:
> > > > 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"
> > >
> > > Will wait until the barrier is released/opened. Then add there is
> > no
> > > option for no wait as found in other APIs.
> >
> > Ok, so
> > "If it is set to ``RTEMS_NO_TIMEOUT``, then the calling task will
> > wait
> > until the barrier is released."
> > ?
> >
> > The whole "If the barrier is available or the ``RTEMS_NO_WAIT``
> > option
> > component is set, then the timeout is ignored." wording is another
> > semaphore leftover that I missed when moving things around.
> >
> > I'm thinking I'll remove that whole sentence. replacing it with one
> > of
> > the following alternatives (or a mix thereof):
> >
> > It is not possible to make the calling task return based on the
> > timeout
> > without wating for at least one clock tick.
> >
> > There is no equivalent to the ``RTEMS_NO_WAIT`` option for this
> > directive,
> > hence the minimum timeout possible is one clock tick.
> >
> > It is not possible to make the calling task return immediately
> > based on the
> > timeout, the minimum timeout is 1 clock tick.
> >
> > The minimum timeout interval is one clock tick and it is
> > therefore not
> > possible to make the calling task return immediately based on
> > the timeout.
> >
> > I'm still not particularly happy with any of them, but I'm a bit
> > stuck
> > for the precise wording.
>
> How about starting with something like, "a barrier is always
> considered
> to be closed (e.g. unavailable) and, consequently, polling does not
> make
> sense. The barrier wait operation always blocks with the option of
> timeout."
>
> When teaching the RTEMS class, I always highlight that Classic API
> blocking operations are poll, block forever, or block with timeout.
> This
> is the sole exception. It is because the barrier is always closed
> when you
> arrive at it. If this can come across somehow in the description,
> that
> would be good.
To me there's two points that is relevant to get accross:
* 0 overlaps with RTEMS_NO_TIMEOUT and hence a zero timeout cannot be
used.
* Zero timeout would imply polling, which is not supported for barriers.
where the latter point might be the more important one?
The way I understand it is that polling a barrier is a weird use case,
but by no means does it make *no* sense to do so. Wanting to know "if i
wait here, would I trip the automatic release and pass or would I
block?" does seem niche but not unreasonable?
Hence at least in my mind, "polling is not supported" is more correct
than "polling does not make sense", unless the whole thing is qualified
with the exception of the last waiter with automatic release, which is
already described below in the next paragraph and hence would be
duplication.
The next paragraph following in the existing documentation is:
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
the barrier is configured for manual release, this rule of thumb will
always be valid. If the barrier is configured for automatic release, all
callers will block except for the one which is the Nth task which trips the
automatic release condition.
--
Martin Erik Werner <martinerikwerner at gmail.com>
More information about the devel
mailing list