[concurrency-interest] Semaphore doc bug [Was: Enforcing ordered execution of critical sections?]

Joe Bowbeer joe.bowbeer at gmail.com
Tue Dec 23 01:19:03 EST 2014


I meant to say something more like:

Advise against adding permits that cannot be acquired by every waiting
thread.  (Or maybe the "next" waiting thread?)

Anyway, I agree it is not clearly stated. I was trying to capture the idea
that is better illustrated in the example: where releasing 5 permits is not
going to help if the only thread selected needs 7.

My interpretation of what Semaphore does is now heavily influenced by what
AQS supports.  I'm glad someone is thinking about what Semaphore *should*
do in addition to what AQS *can* do.

--Joe

On Mon, Dec 22, 2014 at 8:05 PM, David Holmes <davidcholmes at aapt.net.au>
wrote:

> Doug Lea writes:
> > On 12/22/2014 02:19 PM, Joe Bowbeer wrote:
> >
> > > I point out a few places where I think the Semaphore javadoc
> > could be improved
> > > below.
> >
> > Thanks!
> >
> > >
> > > 1. This comment in the class description needs an even strong warning?
> > >
> > > "This class also provides convenience methods to acquire and
> > release multiple
> > > permits at a time. Beware of the increased risk of indefinite
> > postponement when
> > > these methods are used without fairness set true."
> >
> > I can't think of anything better than to recast my posted example. Yes?
> >
> >   * <p>This class also provides convenience methods to {@link
> >   * #acquire(int) acquire} and {@link #release(int) release} multiple
> >   * permits at a time. These methods are generally more efficient and
> >   * effective than loops. However, they do not establish any preference
> >   * order. For example, if thread A invokes @code{s.acquire(3}) and
> >   * thread B invokes @code{s.acquire(2)}, and two permits become
> >   * available, then there is no guarantee that thread B will obtain
> >   * them unless its acquire came first and Semaphore @code{s} is in
> >   * fair mode.
> >   *
> >
> > > ... acquire(int)
> > > I think an additional "and" helps readability,
> >
> > I agree; done.
> >
> > > 3. The release(int) documentation should make it clearer that
> > *only* one waiting
> > > thread is selected?
> > >
> > > "If any threads are trying to acquire permits, then one is
> > selected and given
> > > the permits that were just released."
> >
> > Just clarifying the referent might work at least as well ...
> >
> >       * If any threads are trying to acquire permits, then one thread is
> >
> > ...with less risk of mis-interpreting or not reading the rest of
> > the method.
> >
> > > 4. This statement in the release(int) documentation emboldened me:
> > >
> > > "There is no requirement that a thread that releases a permit
> > must have acquired
> > > that permit by calling acquire. Correct usage of a semaphore is
> > established by
> > > programming convention in the application."
> > >
> > > I'm not sure what to make of the second sentence.  Would this
> > be a good place to
> > > advise against adding permits that cannot be acquired by any
> > waiting thread?
> >
> > We could just kill the second sentence if you think it does more harm
> > than good. I'm not sure why we included it. But I think the above
> > class-level explanation is a better place to put the non-prioritization
> > disclaimer.
>
> We inclued it to make it clear that a Semapore is not a mutex and that
> there
> are no rules on acquire and release in terms of which thread can do which.
> It is perfectly fine for one thread to do all releases() and another to do
> all acquires(). I don't understand what Joe means when he says "advise
> against adding permits that cannot be acquired by any waiting thread?". Any
> permit once added can be acquired.
>
> I'm still trying to distill the essence of the current problem. It still
> seems to teeter between doc bug and implementation bug to me. Will need to
> check my records from when we specified this originally, as I'm sure the
> atomicity of acquire(n) was subject to discussion.
>
> David
>
> > -Doug
> >
> > _______________________________________________
> > Concurrency-interest mailing list
> > Concurrency-interest at cs.oswego.edu
> > http://cs.oswego.edu/mailman/listinfo/concurrency-interest
>
> _______________________________________________
> Concurrency-interest mailing list
> Concurrency-interest at cs.oswego.edu
> http://cs.oswego.edu/mailman/listinfo/concurrency-interest
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cs.oswego.edu/pipermail/concurrency-interest/attachments/20141222/dbb4a785/attachment-0001.html>


More information about the Concurrency-interest mailing list