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

David Holmes davidcholmes at aapt.net.au
Mon Dec 22 23:05:00 EST 2014

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.


> -Doug
> _______________________________________________
> Concurrency-interest mailing list
> Concurrency-interest at cs.oswego.edu
> http://cs.oswego.edu/mailman/listinfo/concurrency-interest

More information about the Concurrency-interest mailing list